@memberjunction/db-auto-doc 6.2.0-edge.4 → 6.2.0-edge.6

package/dist/utils/call-deadline.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A wall-clock ceiling on one model call.
+ *
+ * Every LLM call in this package was unbounded. That is not the same problem as "slow": the retry
+ * loops in `PromptEngine` only engage once a promise settles, and a provider that accepts the
+ * socket and then stops sending bytes never settles one — so a stall bypassed retry, backoff and
+ * error reporting alike and simply parked the run. `maxTokens` bounds the response, not the wait.
+ *
+ * Two mechanisms, deliberately both, mirroring how `AIPromptRunner.createExecutionBound` bounds its
+ * own calls:
+ *
+ *  - the request is ABORTED via `ChatParams.cancellationToken`, which the provider drivers forward
+ *    to their SDKs (`{ signal }` on the OpenAI client, and the equivalent on Gemini, LMStudio and
+ *    BettyBot), so the connection is actually torn down;
+ *  - the awaited promise is REJECTED, so a driver that ignores the signal — or a hang somewhere
+ *    above the SDK — still cannot park the caller forever.
+ *
+ * Either alone is insufficient. Aborting without rejecting trusts every current and future driver
+ * to honour the signal. Rejecting without aborting leaves the request in flight, which is how a
+ * failing provider ends up holding ten open sockets while the caller opens an eleventh.
+ */
+/** Default ceiling when `AIConfig.callTimeoutMs` is not set. */
+export declare const DEFAULT_CALL_TIMEOUT_MS = 120000;
+/** Resolves the configured ceiling. `0` (or a negative value) means no bound. */
+export declare function ResolveCallTimeoutMs(configured: number | undefined): number;
+/** Thrown when a model call exceeds its configured ceiling. */
+export declare class LLMCallTimeoutError extends Error {
+    readonly TimeoutMs: number;
+    constructor(timeoutMs: number, what: string);
+}
+/**
+ * Runs `call` under a wall-clock ceiling.
+ *
+ * `call` receives the AbortSignal to attach to its `ChatParams.cancellationToken`. When
+ * `timeoutMs` is 0 the signal is `undefined` and the call runs exactly as it did before this
+ * existed, so disabling the bound restores the previous behaviour rather than approximating it.
+ *
+ * @param timeoutMs Resolved ceiling; 0 disables.
+ * @param what Description used in the timeout message (a prompt or table name).
+ * @param call Issues the request, attaching the supplied signal.
+ */
+export declare function WithCallDeadline<T>(timeoutMs: number, what: string, call: (signal: AbortSignal | undefined) => Promise<T>): Promise<T>;
+//# sourceMappingURL=call-deadline.d.ts.map

package/dist/utils/call-deadline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-deadline.d.ts","sourceRoot":"","sources":["../../src/utils/call-deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gEAAgE;AAChE,eAAO,MAAM,uBAAuB,SAAU,CAAC;AAE/C,iFAAiF;AACjF,wBAAgB,oBAAoB,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAK3E;AAED,+DAA+D;AAC/D,qBAAa,mBAAoB,SAAQ,KAAK;IAC5C,SAAgB,SAAS,EAAE,MAAM,CAAC;gBAEtB,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM;CAQ5C;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACtC,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,CAAC,MAAM,EAAE,WAAW,GAAG,SAAS,KAAK,OAAO,CAAC,CAAC,CAAC,GACpD,OAAO,CAAC,CAAC,CAAC,CA4BZ"}

package/dist/utils/call-deadline.js

@@ -0,0 +1,81 @@
+/**
+ * A wall-clock ceiling on one model call.
+ *
+ * Every LLM call in this package was unbounded. That is not the same problem as "slow": the retry
+ * loops in `PromptEngine` only engage once a promise settles, and a provider that accepts the
+ * socket and then stops sending bytes never settles one — so a stall bypassed retry, backoff and
+ * error reporting alike and simply parked the run. `maxTokens` bounds the response, not the wait.
+ *
+ * Two mechanisms, deliberately both, mirroring how `AIPromptRunner.createExecutionBound` bounds its
+ * own calls:
+ *
+ *  - the request is ABORTED via `ChatParams.cancellationToken`, which the provider drivers forward
+ *    to their SDKs (`{ signal }` on the OpenAI client, and the equivalent on Gemini, LMStudio and
+ *    BettyBot), so the connection is actually torn down;
+ *  - the awaited promise is REJECTED, so a driver that ignores the signal — or a hang somewhere
+ *    above the SDK — still cannot park the caller forever.
+ *
+ * Either alone is insufficient. Aborting without rejecting trusts every current and future driver
+ * to honour the signal. Rejecting without aborting leaves the request in flight, which is how a
+ * failing provider ends up holding ten open sockets while the caller opens an eleventh.
+ */
+/** Default ceiling when `AIConfig.callTimeoutMs` is not set. */
+export const DEFAULT_CALL_TIMEOUT_MS = 120_000;
+/** Resolves the configured ceiling. `0` (or a negative value) means no bound. */
+export function ResolveCallTimeoutMs(configured) {
+    if (configured === undefined) {
+        return DEFAULT_CALL_TIMEOUT_MS;
+    }
+    return Number.isFinite(configured) && configured > 0 ? configured : 0;
+}
+/** Thrown when a model call exceeds its configured ceiling. */
+export class LLMCallTimeoutError extends Error {
+    constructor(timeoutMs, what) {
+        // The word "timeout" is load-bearing: PromptEngine.isRetryableError and MJ's own ErrorAnalyzer
+        // both classify on message text, and a stall should be treated as retriable rather than fatal.
+        super(`${what} exceeded its ${timeoutMs}ms call timeout — the model call was aborted (timeout)`);
+        this.name = 'LLMCallTimeoutError';
+        this.TimeoutMs = timeoutMs;
+        Object.setPrototypeOf(this, LLMCallTimeoutError.prototype);
+    }
+}
+/**
+ * Runs `call` under a wall-clock ceiling.
+ *
+ * `call` receives the AbortSignal to attach to its `ChatParams.cancellationToken`. When
+ * `timeoutMs` is 0 the signal is `undefined` and the call runs exactly as it did before this
+ * existed, so disabling the bound restores the previous behaviour rather than approximating it.
+ *
+ * @param timeoutMs Resolved ceiling; 0 disables.
+ * @param what Description used in the timeout message (a prompt or table name).
+ * @param call Issues the request, attaching the supplied signal.
+ */
+export async function WithCallDeadline(timeoutMs, what, call) {
+    if (timeoutMs <= 0) {
+        return call(undefined);
+    }
+    const controller = new AbortController();
+    let timer;
+    const expiry = new Promise((_resolve, reject) => {
+        timer = setTimeout(() => {
+            const err = new LLMCallTimeoutError(timeoutMs, what);
+            // Abort first so the in-flight request is cancelled, THEN reject. Rejecting first would let
+            // the caller move on — and start its next request — while this one is still open.
+            if (!controller.signal.aborted) {
+                controller.abort(err);
+            }
+            reject(err);
+        }, timeoutMs);
+    });
+    try {
+        return await Promise.race([call(controller.signal), expiry]);
+    }
+    finally {
+        // Always release the timer, on success, failure and timeout alike: a long-lived process would
+        // otherwise accumulate one per call.
+        if (timer) {
+            clearTimeout(timer);
+        }
+    }
+}
+//# sourceMappingURL=call-deadline.js.map

package/dist/utils/call-deadline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-deadline.js","sourceRoot":"","sources":["../../src/utils/call-deadline.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,uBAAuB,GAAG,OAAO,CAAC;AAE/C,iFAAiF;AACjF,MAAM,UAAU,oBAAoB,CAAC,UAA8B;IACjE,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,OAAO,uBAAuB,CAAC;IACjC,CAAC;IACD,OAAO,MAAM,CAAC,QAAQ,CAAC,UAAU,CAAC,IAAI,UAAU,GAAG,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACxE,CAAC;AAED,+DAA+D;AAC/D,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IAG5C,YAAY,SAAiB,EAAE,IAAY;QACzC,+FAA+F;QAC/F,+FAA+F;QAC/F,KAAK,CAAC,GAAG,IAAI,iBAAiB,SAAS,wDAAwD,CAAC,CAAC;QACjG,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;QAClC,IAAI,CAAC,SAAS,GAAG,SAAS,CAAC;QAC3B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,mBAAmB,CAAC,SAAS,CAAC,CAAC;IAC7D,CAAC;CACF;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAAiB,EACjB,IAAY,EACZ,IAAqD;IAErD,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;QACnB,OAAO,IAAI,CAAC,SAAS,CAAC,CAAC;IACzB,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;IACzC,IAAI,KAAgD,CAAC;IACrD,MAAM,MAAM,GAAG,IAAI,OAAO,CAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,EAAE;QACrD,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE;YACtB,MAAM,GAAG,GAAG,IAAI,mBAAmB,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;YACrD,4FAA4F;YAC5F,kFAAkF;YAClF,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;gBAC/B,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;YACxB,CAAC;YACD,MAAM,CAAC,GAAG,CAAC,CAAC;QACd,CAAC,EAAE,SAAS,CAAC,CAAC;IAChB,CAAC,CAAC,CAAC;IAEH,IAAI,CAAC;QACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC;IAC/D,CAAC;YAAS,CAAC;QACT,8FAA8F;QAC9F,qCAAqC;QACrC,IAAI,KAAK,EAAE,CAAC;YACV,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/utils/config-loader.d.ts

@@ -35,5 +35,10 @@ export declare class ConfigLoader {
      * Validate configuration
      */
     private static validate;
+    /**
+     * Resolve seedContext.file or seedContext.files if specified,
+     * reading contents and appending to customInstructions.
+     */
+    private static resolveSeedContextFiles;
 }
 //# sourceMappingURL=config-loader.d.ts.map

package/dist/utils/config-loader.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,qBAAa,YAAY;IACvB;;;OAGG;WACiB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAqBtE,oCAAoC;WAChB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAItE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B;;OAEG;WACiB,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpF,oCAAoC;WAChB,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;OAEG;WACW,aAAa,IAAI,eAAe;IAuD9C,6CAA6C;WAC/B,aAAa,IAAI,eAAe;IAI9C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAkB5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;CA6BxB"}
+{"version":3,"file":"config-loader.d.ts","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAErD,qBAAa,YAAY;IACvB;;;OAGG;WACiB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAwBtE,oCAAoC;WAChB,IAAI,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAItE;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAU5B;;OAEG;WACiB,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYpF,oCAAoC;WAChB,IAAI,CAAC,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpF;;OAEG;WACW,aAAa,IAAI,eAAe;IAuD9C,6CAA6C;WAC/B,aAAa,IAAI,eAAe;IAI9C;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,aAAa;IAkB5B;;OAEG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ;IA+BvB;;;OAGG;mBACkB,uBAAuB;CA+B7C"}

package/dist/utils/config-loader.js

@@ -14,6 +14,8 @@ export class ConfigLoader {
             // Expand environment variables in the content
             const expandedContent = this.expandEnvVars(content);
             const config = JSON.parse(expandedContent);
+            // Resolve seedContext.file or seedContext.files if specified
+            await this.resolveSeedContextFiles(config, path.dirname(configPath));
             // Validate required fields
             this.validate(config);
             // Apply defaults for optional sections
@@ -162,9 +164,44 @@ export class ConfigLoader {
         if (!config.ai.model) {
             throw new Error('Missing ai.model');
         }
+        config.ai.model = config.ai.model.trim();
         if (!config.ai.apiKey) {
             throw new Error('Missing ai.apiKey');
         }
     }
+    /**
+     * Resolve seedContext.file or seedContext.files if specified,
+     * reading contents and appending to customInstructions.
+     */
+    static async resolveSeedContextFiles(config, baseDir) {
+        if (!config.seedContext)
+            return;
+        const filesToLoad = [];
+        if (config.seedContext.file) {
+            filesToLoad.push(config.seedContext.file);
+        }
+        if (Array.isArray(config.seedContext.files)) {
+            filesToLoad.push(...config.seedContext.files);
+        }
+        if (filesToLoad.length === 0)
+            return;
+        const contents = [];
+        for (const relOrAbsPath of filesToLoad) {
+            const resolvedPath = path.isAbsolute(relOrAbsPath)
+                ? relOrAbsPath
+                : path.resolve(baseDir, relOrAbsPath);
+            try {
+                contents.push(await fs.readFile(resolvedPath, 'utf-8'));
+            }
+            catch (error) {
+                const setting = config.seedContext.file === relOrAbsPath ? 'seedContext.file' : 'seedContext.files';
+                throw new Error(`Could not read ${setting} entry '${relOrAbsPath}' (resolved to ${resolvedPath}): ${error.message}`);
+            }
+        }
+        const loadedText = contents.join('\n\n---\n\n');
+        config.seedContext.customInstructions = config.seedContext.customInstructions
+            ? `${config.seedContext.customInstructions}\n\n${loadedText}`
+            : loadedText;
+    }
 }
 //# sourceMappingURL=config-loader.js.map

package/dist/utils/config-loader.js.map

@@ -1 +1 @@
-{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config-loader.js","sourceRoot":"","sources":["../../src/utils/config-loader.ts"],"names":[],"mappings":"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"}

package/dist/utils/index-hints.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Existing indexes as evidence for the LLM passes.
+ *
+ * Databases "in the wild" often declare no primary or foreign keys but still have indexes on the
+ * columns people join and filter on. A unique index on non-null columns usually marks a primary or
+ * alternate key, and a non-unique index led by an ID-like column often marks a foreign key. These
+ * helpers turn the indexes stored on a table (`TableDefinition.indexes`) into prompt context.
+ */
+import type { AutoDocIndex } from '../types/driver.js';
+import type { SchemaDefinition, TableDefinition } from '../types/state.js';
+/** One existing index, trimmed to what a prompt needs. */
+export interface IndexHint {
+    Columns: string[];
+    IncludeColumns: string[];
+    IsUnique: boolean;
+    IsPrimaryKey: boolean;
+    /** Partial-index predicate, when the index covers only some rows. */
+    Filter?: string;
+}
+/** Most indexes a single table contributes to a prompt. */
+export declare const MAX_INDEX_HINTS_PER_TABLE = 25;
+/**
+ * The table's indexes as prompt hints, primary key first, then unique, then the rest, capped at
+ * `max`. Returns an empty array when the table has none or they were not loaded.
+ */
+export declare function BuildIndexHints(table: Pick<TableDefinition, 'indexes'> | undefined, max?: number): IndexHint[];
+/** One line per hint, e.g. `UNIQUE (Code) INCLUDE (Name) WHERE (Active = 1)`. */
+export declare function FormatIndexHint(hint: IndexHint): string;
+/**
+ * True when the column alone is the key of a primary-key or unique, unfiltered index on the table,
+ * i.e. the database already guarantees its values are distinct. Undefined when indexes were not loaded.
+ */
+export declare function IsUniquelyIndexed(table: Pick<TableDefinition, 'indexes'> | undefined, column: string): boolean | undefined;
+/** Attaches catalog indexes to the matching tables (exact name first, then case-insensitive). */
+export declare function AttachIndexesToTables(tables: TableDefinition[], indexes: AutoDocIndex[]): void;
+/**
+ * Decides which schemas still need their indexes read, honoring `analysis.useExistingIndexes`.
+ * When it is off, indexes left in a resumed state by an earlier run are dropped, so neither the prompt
+ * hints nor index-backed PK candidates use them, and nothing is returned to load. Otherwise returns the
+ * schemas with at least one table whose indexes were never read.
+ */
+export declare function PrepareIndexesForRun(schemas: SchemaDefinition[], useExistingIndexes: boolean | undefined): SchemaDefinition[];
+//# sourceMappingURL=index-hints.d.ts.map

package/dist/utils/index-hints.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-hints.d.ts","sourceRoot":"","sources":["../../src/utils/index-hints.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAE3E,0DAA0D;AAC1D,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,EAAE,OAAO,CAAC;IACtB,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,2DAA2D;AAC3D,eAAO,MAAM,yBAAyB,KAAK,CAAC;AAE5C;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,SAAS,EAAE,GAAG,SAA4B,GAAG,SAAS,EAAE,CAYjI;AAED,iFAAiF;AACjF,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,CAKvD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,IAAI,CAAC,eAAe,EAAE,SAAS,CAAC,GAAG,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAQ1H;AAED,iGAAiG;AACjG,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,eAAe,EAAE,EAAE,OAAO,EAAE,YAAY,EAAE,GAAG,IAAI,CAc9F;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,EAAE,EAAE,kBAAkB,EAAE,OAAO,GAAG,SAAS,GAAG,gBAAgB,EAAE,CAQ7H"}

package/dist/utils/index-hints.js

@@ -0,0 +1,80 @@
+/**
+ * Existing indexes as evidence for the LLM passes.
+ *
+ * Databases "in the wild" often declare no primary or foreign keys but still have indexes on the
+ * columns people join and filter on. A unique index on non-null columns usually marks a primary or
+ * alternate key, and a non-unique index led by an ID-like column often marks a foreign key. These
+ * helpers turn the indexes stored on a table (`TableDefinition.indexes`) into prompt context.
+ */
+/** Most indexes a single table contributes to a prompt. */
+export const MAX_INDEX_HINTS_PER_TABLE = 25;
+/**
+ * The table's indexes as prompt hints, primary key first, then unique, then the rest, capped at
+ * `max`. Returns an empty array when the table has none or they were not loaded.
+ */
+export function BuildIndexHints(table, max = MAX_INDEX_HINTS_PER_TABLE) {
+    const indexes = table?.indexes ?? [];
+    return [...indexes]
+        .sort((a, b) => hintRank(a) - hintRank(b))
+        .slice(0, max)
+        .map((ix) => ({
+        Columns: ix.Columns,
+        IncludeColumns: ix.IncludeColumns,
+        IsUnique: ix.IsUnique || ix.IsPrimaryKey,
+        IsPrimaryKey: ix.IsPrimaryKey,
+        Filter: ix.FilterDefinition || undefined
+    }));
+}
+/** One line per hint, e.g. `UNIQUE (Code) INCLUDE (Name) WHERE (Active = 1)`. */
+export function FormatIndexHint(hint) {
+    const kind = hint.IsPrimaryKey ? 'PRIMARY KEY' : hint.IsUnique ? 'UNIQUE' : 'INDEX';
+    const include = hint.IncludeColumns.length ? ` INCLUDE (${hint.IncludeColumns.join(', ')})` : '';
+    const filter = hint.Filter ? ` WHERE ${hint.Filter}` : '';
+    return `${kind} (${hint.Columns.join(', ')})${include}${filter}`;
+}
+/**
+ * True when the column alone is the key of a primary-key or unique, unfiltered index on the table,
+ * i.e. the database already guarantees its values are distinct. Undefined when indexes were not loaded.
+ */
+export function IsUniquelyIndexed(table, column) {
+    if (!table?.indexes) {
+        return undefined;
+    }
+    const target = column.toLowerCase();
+    return table.indexes.some((ix) => (ix.IsUnique || ix.IsPrimaryKey) && !ix.FilterDefinition && ix.Columns.length === 1 && ix.Columns[0].toLowerCase() === target);
+}
+/** Attaches catalog indexes to the matching tables (exact name first, then case-insensitive). */
+export function AttachIndexesToTables(tables, indexes) {
+    const exact = new Map();
+    for (const ix of indexes) {
+        const list = exact.get(ix.TableName) ?? [];
+        list.push(ix);
+        exact.set(ix.TableName, list);
+    }
+    const folded = new Map();
+    for (const [name, list] of exact) {
+        folded.set(name.toLowerCase(), [...(folded.get(name.toLowerCase()) ?? []), ...list]);
+    }
+    for (const table of tables) {
+        table.indexes = exact.get(table.name) ?? folded.get(table.name.toLowerCase()) ?? [];
+    }
+}
+/**
+ * Decides which schemas still need their indexes read, honoring `analysis.useExistingIndexes`.
+ * When it is off, indexes left in a resumed state by an earlier run are dropped, so neither the prompt
+ * hints nor index-backed PK candidates use them, and nothing is returned to load. Otherwise returns the
+ * schemas with at least one table whose indexes were never read.
+ */
+export function PrepareIndexesForRun(schemas, useExistingIndexes) {
+    if (useExistingIndexes === false) {
+        for (const table of schemas.flatMap((s) => s.tables)) {
+            delete table.indexes;
+        }
+        return [];
+    }
+    return schemas.filter((s) => s.tables.some((t) => t.indexes === undefined));
+}
+function hintRank(ix) {
+    return ix.IsPrimaryKey ? 0 : ix.IsUnique ? 1 : 2;
+}
+//# sourceMappingURL=index-hints.js.map

package/dist/utils/index-hints.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-hints.js","sourceRoot":"","sources":["../../src/utils/index-hints.ts"],"names":[],"mappings":"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"}

package/dist/utils/index.d.ts

@@ -2,4 +2,6 @@
  * Exports for utils module
  */
 export { ConfigLoader } from './config-loader.js';
+export * from './index-hints.js';
+export * from './seed-context.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}

package/dist/utils/index.js

@@ -2,4 +2,6 @@
  * Exports for utils module
  */
 export { ConfigLoader } from './config-loader.js';
+export * from './index-hints.js';
+export * from './seed-context.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC"}

package/dist/utils/llm-factory.d.ts

@@ -5,6 +5,7 @@
  * across PromptEngine and LLMSanityChecker.
  */
 import { BaseLLM } from '@memberjunction/ai';
+import '@memberjunction/server-bootstrap-lite/mj-class-registrations';
 /**
  * Create an LLM instance from a provider name
  *

package/dist/utils/llm-factory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"llm-factory.d.ts","sourceRoot":"","sources":["../../src/utils/llm-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAoB7C;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAuB3E;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,qDAAqD;AACrD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD"}
+{"version":3,"file":"llm-factory.d.ts","sourceRoot":"","sources":["../../src/utils/llm-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI7C,OAAO,8DAA8D,CAAC;AAmBtE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAyB3E;AAED,iDAAiD;AACjD,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAE3E;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED,kDAAkD;AAClD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAEvE;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAED,qDAAqD;AACrD,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD"}

package/dist/utils/llm-factory.js

@@ -6,6 +6,9 @@
  */
 import { BaseLLM } from '@memberjunction/ai';
 import { MJGlobal } from '@memberjunction/global';
+// The LLM drivers register with MJGlobal.ClassFactory as a side effect of this manifest; without it a
+// standalone CLI process has no provider classes to instantiate.
+import '@memberjunction/server-bootstrap-lite/mj-class-registrations';
 /**
  * Provider name to LLM driver class name mapping
  */
@@ -37,7 +40,9 @@ export function CreateLLMInstance(provider, apiKey) {
         throw new Error(`Unknown provider: ${provider}. Supported providers: ${supportedProviders}`);
     }
     const llm = MJGlobal.Instance.ClassFactory.CreateInstance(BaseLLM, driverClass, apiKey);
-    if (!llm) {
+    // The ClassFactory falls back to the base class when nothing is registered under the key, and a bare
+    // BaseLLM fails on every call, so treat that as "not installed" too.
+    if (!llm || Object.getPrototypeOf(llm) === BaseLLM.prototype) {
         throw new Error(`Failed to create LLM instance for provider: ${provider} (driver class: ${driverClass}). Check that the provider is installed.`);
     }
     return llm;

package/dist/utils/llm-factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"llm-factory.js","sourceRoot":"","sources":["../../src/utils/llm-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAElD;;GAEG;AACH,MAAM,wBAAwB,GAA2B;IACvD,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,cAAc;IAC3B,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,YAAY;IACvB,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,aAAa;IACzB,YAAY,EAAE,eAAe;IAC7B,KAAK,EAAE,QAAQ;IACf,SAAS,EAAE,YAAY;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IAChE,MAAM,WAAW,GAAG,wBAAwB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IAErE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5E,MAAM,IAAI,KAAK,CACb,qBAAqB,QAAQ,0BAA0B,kBAAkB,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,cAAc,CACvD,OAAO,EACP,WAAW,EACX,MAAM,CACP,CAAC;IAEF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,MAAM,IAAI,KAAK,CACb,+CAA+C,QAAQ,mBAAmB,WAAW,0CAA0C,CAChI,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IAChE,OAAO,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,wBAAwB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;AAC/C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,qBAAqB;IACnC,OAAO,qBAAqB,EAAE,CAAC;AACjC,CAAC"}
+{"version":3,"file":"llm-factory.js","sourceRoot":"","sources":["../../src/utils/llm-factory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAC7C,OAAO,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAClD,sGAAsG;AACtG,iEAAiE;AACjE,OAAO,8DAA8D,CAAC;AAEtE;;GAEG;AACH,MAAM,wBAAwB,GAA2B;IACvD,QAAQ,EAAE,WAAW;IACrB,QAAQ,EAAE,WAAW;IACrB,WAAW,EAAE,cAAc;IAC3B,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,YAAY;IACvB,QAAQ,EAAE,WAAW;IACrB,OAAO,EAAE,UAAU;IACnB,UAAU,EAAE,aAAa;IACzB,YAAY,EAAE,eAAe;IAC7B,KAAK,EAAE,QAAQ;IACf,SAAS,EAAE,YAAY;CACxB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IAChE,MAAM,WAAW,GAAG,wBAAwB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IAErE,IAAI,CAAC,WAAW,EAAE,CAAC;QACjB,MAAM,kBAAkB,GAAG,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC5E,MAAM,IAAI,KAAK,CACb,qBAAqB,QAAQ,0BAA0B,kBAAkB,EAAE,CAC5E,CAAC;IACJ,CAAC;IAED,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC,cAAc,CACvD,OAAO,EACP,WAAW,EACX,MAAM,CACP,CAAC;IAEF,qGAAqG;IACrG,qEAAqE;IACrE,IAAI,CAAC,GAAG,IAAI,MAAM,CAAC,cAAc,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,KAAK,CACb,+CAA+C,QAAQ,mBAAmB,WAAW,0CAA0C,CAChI,CAAC;IACJ,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,iDAAiD;AACjD,MAAM,UAAU,iBAAiB,CAAC,QAAgB,EAAE,MAAc;IAChE,OAAO,iBAAiB,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,wBAAwB,CAAC,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;AAC1D,CAAC;AAED,kDAAkD;AAClD,MAAM,UAAU,kBAAkB,CAAC,QAAgB;IACjD,OAAO,kBAAkB,CAAC,QAAQ,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,MAAM,CAAC,IAAI,CAAC,wBAAwB,CAAC,CAAC;AAC/C,CAAC;AAED,qDAAqD;AACrD,MAAM,UAAU,qBAAqB;IACnC,OAAO,qBAAqB,EAAE,CAAC;AACjC,CAAC"}

package/dist/utils/seed-context.d.ts

@@ -0,0 +1,23 @@
+/**
+ * The part of the operator's seed context (`seedContext.customInstructions`, which also holds the
+ * text of `seedContext.file` / `files`) that is worth sending to a key-inference prompt.
+ *
+ * The table-analysis prompt gets the whole text. The PK/FK passes run once per table, so sending a
+ * long data-layout document to each of them would multiply its cost by the table count. A
+ * per-table pass gets only the paragraphs that name its table; a whole-schema pass gets the text.
+ * Both are capped.
+ */
+/** Default cap on the seed text sent to one key-inference prompt, in characters. */
+export declare const DEFAULT_SEED_KEY_PASS_MAX_CHARS = 6000;
+/** The fields of a seed context this module reads; satisfied by both the config and state shapes. */
+export interface SeedContextText {
+    customInstructions?: string;
+    keyPassMaxChars?: number;
+}
+/**
+ * Returns the seed text for a key-inference prompt, or undefined when there is none to send.
+ * @param seed the seed context from config or state
+ * @param tableNames the tables the prompt is about; empty for a whole-schema prompt
+ */
+export declare function SeedContextExcerpt(seed: SeedContextText | undefined, tableNames: string[]): string | undefined;
+//# sourceMappingURL=seed-context.d.ts.map

package/dist/utils/seed-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-context.d.ts","sourceRoot":"","sources":["../../src/utils/seed-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oFAAoF;AACpF,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD,qGAAqG;AACrG,MAAM,WAAW,eAAe;IAC9B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,eAAe,GAAG,SAAS,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,MAAM,GAAG,SAAS,CAmB9G"}

package/dist/utils/seed-context.js

@@ -0,0 +1,38 @@
+/**
+ * The part of the operator's seed context (`seedContext.customInstructions`, which also holds the
+ * text of `seedContext.file` / `files`) that is worth sending to a key-inference prompt.
+ *
+ * The table-analysis prompt gets the whole text. The PK/FK passes run once per table, so sending a
+ * long data-layout document to each of them would multiply its cost by the table count. A
+ * per-table pass gets only the paragraphs that name its table; a whole-schema pass gets the text.
+ * Both are capped.
+ */
+/** Default cap on the seed text sent to one key-inference prompt, in characters. */
+export const DEFAULT_SEED_KEY_PASS_MAX_CHARS = 6000;
+/**
+ * Returns the seed text for a key-inference prompt, or undefined when there is none to send.
+ * @param seed the seed context from config or state
+ * @param tableNames the tables the prompt is about; empty for a whole-schema prompt
+ */
+export function SeedContextExcerpt(seed, tableNames) {
+    const text = seed?.customInstructions?.trim();
+    const maxChars = seed?.keyPassMaxChars ?? DEFAULT_SEED_KEY_PASS_MAX_CHARS;
+    if (!text || maxChars <= 0) {
+        return undefined;
+    }
+    let excerpt = text;
+    if (tableNames.length > 0) {
+        const matchers = tableNames.map(name => new RegExp(`(^|[^A-Za-z0-9_])${escapeRegExp(name)}([^A-Za-z0-9_]|$)`, 'i'));
+        const paragraphs = text.split(/\n\s*\n/).map(p => p.trim()).filter(p => p.length > 0);
+        const relevant = paragraphs.filter(p => matchers.some(m => m.test(p)));
+        if (relevant.length === 0) {
+            return undefined;
+        }
+        excerpt = relevant.join('\n\n');
+    }
+    return excerpt.length > maxChars ? `${excerpt.slice(0, maxChars)}\n…(truncated)` : excerpt;
+}
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+//# sourceMappingURL=seed-context.js.map

package/dist/utils/seed-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-context.js","sourceRoot":"","sources":["../../src/utils/seed-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,oFAAoF;AACpF,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAC;AAQpD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAiC,EAAE,UAAoB;IACxF,MAAM,IAAI,GAAG,IAAI,EAAE,kBAAkB,EAAE,IAAI,EAAE,CAAC;IAC9C,MAAM,QAAQ,GAAG,IAAI,EAAE,eAAe,IAAI,+BAA+B,CAAC;IAC1E,IAAI,CAAC,IAAI,IAAI,QAAQ,IAAI,CAAC,EAAE,CAAC;QAC3B,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,MAAM,CAAC,oBAAoB,YAAY,CAAC,IAAI,CAAC,mBAAmB,EAAE,GAAG,CAAC,CAAC,CAAC;QACpH,MAAM,UAAU,GAAG,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;QACtF,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;QACvE,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAClC,CAAC;IAED,OAAO,OAAO,CAAC,MAAM,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,gBAAgB,CAAC,CAAC,CAAC,OAAO,CAAC;AAC7F,CAAC;AAED,SAAS,YAAY,CAAC,IAAY;IAChC,OAAO,IAAI,CAAC,OAAO,CAAC,qBAAqB,EAAE,MAAM,CAAC,CAAC;AACrD,CAAC"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@memberjunction/db-auto-doc",
   "type": "module",
-  "version": "6.2.0-edge.4",
+  "version": "6.2.0-edge.6",
   "description": "AI-powered database documentation generator for SQL Server, MySQL, and PostgreSQL. Analyzes your database structure, uses AI to generate comprehensive descriptions, and saves them as metadata. Works standalone - no MemberJunction runtime required.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -64,10 +64,10 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^8.2.0",
-    "@memberjunction/ai": "6.2.0-edge.4",
-    "@memberjunction/server-bootstrap-lite": "6.2.0-edge.4",
-    "@memberjunction/core": "6.2.0-edge.4",
-    "@memberjunction/global": "6.2.0-edge.4",
+    "@memberjunction/ai": "6.2.0-edge.6",
+    "@memberjunction/server-bootstrap-lite": "6.2.0-edge.6",
+    "@memberjunction/core": "6.2.0-edge.6",
+    "@memberjunction/global": "6.2.0-edge.6",
     "@oclif/core": "^3.27.0",
     "@oclif/plugin-help": "^6.2.37",
     "chalk": "^5.6.2",

package/prompts/fk-pruning-holistic.md

@@ -20,6 +20,13 @@ The per-table analysis proposed removing these FKs. Review each one and decide w
    - **Removal reason**: {{ proposal.reasoning }}
 {% endfor %}
 
+{% if seedExcerpt %}
+## Notes from the operator about this data
+Written by the person running the analysis. Treat them as evidence about how tables relate and which columns are keys; they do not override what the data and constraints show.
+
+{{ seedExcerpt }}
+
+{% endif %}
 ## Review Guidelines
 
 Consider the FULL relationship graph when making decisions:

package/prompts/fk-pruning-table.md

@@ -14,9 +14,28 @@ These FKs were identified by statistical analysis and/or LLM analysis. Some are
 **NOTE**: FKs marked as **[LOCKED]** have very high confidence and CANNOT be removed. Only evaluate the unlocked ones.
 
 {% for fk in candidates %}
-{{ loop.index }}. {% if fk.locked %}**[LOCKED]** {% endif %}**{{ fk.sourceColumn }}** → {{ fk.targetSchema }}.{{ fk.targetTable }}.{{ fk.targetColumn }} (confidence: {{ fk.confidence }}%)
+{{ loop.index }}. {% if fk.locked %}**[LOCKED]** {% endif %}**{{ fk.sourceColumn }}** → {{ fk.targetSchema }}.{{ fk.targetTable }}.{{ fk.targetColumn }} (confidence: {{ fk.confidence }}%{% if fk.targetUniquelyIndexed === true %}; target column has a unique index{% elif fk.targetUniquelyIndexed === false %}; target column has no unique index{% endif %})
 {% endfor %}
 
+{% if existingIndexes and existingIndexes.length > 0 %}
+## Existing Indexes
+These indexes exist on this table in the database. Developers index the columns they join and filter on, so indexes are clues to keys even when none are declared:
+{% for ix in existingIndexes %}
+- {{ ix }}
+{% endfor %}
+
+*A UNIQUE index or PRIMARY KEY on non-null columns is strong evidence of the primary key (or an alternate key). A non-unique index led by an ID- or code-like column often marks a foreign key. Indexes are evidence, not proof — weigh them with names, statistics and value overlap. "(expression)" is a computed key part.*
+{% endif %}
+
+*A real FK target is normally unique. A target column with a unique index or primary key supports the FK; one without is weaker evidence (but the database may simply not declare it).*
+
+{% if seedExcerpt %}
+## Notes from the operator about this data
+Written by the person running the analysis. Treat them as evidence about how tables relate and which columns are keys; they do not override what the data and constraints show.
+
+{{ seedExcerpt }}
+
+{% endif %}
 ## What to look for when proposing removals:
 
 1. **Reverse direction**: FK goes from parent→child instead of child→parent. Example: `Department.DepartmentID → EmployeeDepartmentHistory.DepartmentID` is backwards — the history table should reference Department, not the other way around.

package/prompts/pk-pruning-holistic.md

@@ -11,6 +11,13 @@ You are performing a final review of proposed primary key removals across a data
 - {{ tbl.schema }}.{{ tbl.name }}{% if tbl.pk %} (PK: {{ tbl.pk }}){% endif %}{% if tbl.description %} — {{ tbl.description }}{% endif %}
 {% endfor %}
 
+{% if seedExcerpt %}
+## Notes from the operator about this data
+Written by the person running the analysis. Treat them as evidence about how tables relate and which columns are keys; they do not override what the data and constraints show.
+
+{{ seedExcerpt }}
+
+{% endif %}
 ## Your Task:
 Review each proposed removal. Consider:
 1. Would removing this PK leave the table without any primary key?