@openontology/opencode-palantir 0.1.5 → 0.1.6

package/dist/index.js

@@ -1,6 +1,6 @@
 // @bun
 // src/index.ts
-import path4 from "path";
+import path5 from "path";
 import { tool } from "@opencode-ai/plugin/tool";
 
 // node_modules/hyparquet/src/constants.js
@@ -71,11 +71,6 @@ var PageTypes = [
   "DICTIONARY_PAGE",
   "DATA_PAGE_V2"
 ];
-var BoundaryOrders = [
-  "UNORDERED",
-  "ASCENDING",
-  "DESCENDING"
-];
 var EdgeInterpolationAlgorithms = [
   "SPHERICAL",
   "VINCENTY",
@@ -872,30 +867,6 @@ function pageLocation(loc) {
 }
 
 // node_modules/hyparquet/src/utils.js
-function toJson(obj) {
-  if (obj === undefined)
-    return null;
-  if (typeof obj === "bigint")
-    return Number(obj);
-  if (Object.is(obj, -0))
-    return 0;
-  if (Array.isArray(obj))
-    return obj.map(toJson);
-  if (obj instanceof Uint8Array)
-    return Array.from(obj);
-  if (obj instanceof Date)
-    return obj.toISOString();
-  if (obj instanceof Object) {
-    const newObj = {};
-    for (const key of Object.keys(obj)) {
-      if (obj[key] === undefined)
-        continue;
-      newObj[key] = toJson(obj[key]);
-    }
-    return newObj;
-  }
-  return obj;
-}
 function concat(aaa, bbb) {
   const chunk = 1e4;
   for (let i = 0;i < bbb.length; i += chunk) {
@@ -953,9 +924,9 @@ function columnsNeededForFilter(filter) {
   } else if ("$nor" in filter && Array.isArray(filter.$nor)) {
     columns.push(...filter.$nor.flatMap(columnsNeededForFilter));
   } else {
-    columns.push(...Object.keys(filter));
+    columns.push(...Object.keys(filter).map((key) => key.split(".")[0]));
   }
-  return columns;
+  return [...new Set(columns)];
 }
 function matchFilter(record, filter, strict = true) {
   if ("$and" in filter && Array.isArray(filter.$and)) {
@@ -968,7 +939,7 @@ function matchFilter(record, filter, strict = true) {
     return !filter.$nor.some((subQuery) => matchFilter(record, subQuery, strict));
   }
   return Object.entries(filter).every(([field, condition]) => {
-    const value = record[field];
+    const value = resolve(record, field);
     if (typeof condition !== "object" || condition === null || Array.isArray(condition)) {
       return equals(value, condition, strict);
     }
@@ -1040,6 +1011,13 @@ function canSkipRowGroup({ rowGroup, physicalColumns, filter, strict = true }) {
   }
   return false;
 }
+function resolve(record, path) {
+  let value = record;
+  for (const part of path.split(".")) {
+    value = value?.[part];
+  }
+  return value;
+}
 
 // node_modules/hyparquet/src/plan.js
 var runLimit = 1 << 21;
@@ -2093,6 +2071,7 @@ function readColumn(reader, { groupStart, selectStart, selectEnd }, columnDecode
   let dictionary = undefined;
   let lastChunk = undefined;
   let rowCount = 0;
+  let skipped = 0;
   const emitLastChunk = onPage && (() => {
     lastChunk && onPage({
       pathInSchema,
@@ -2106,23 +2085,29 @@ function readColumn(reader, { groupStart, selectStart, selectEnd }, columnDecode
       break;
     const header = parquetHeader(reader);
     if (header.type === "DICTIONARY_PAGE") {
-      dictionary = readPage(reader, header, columnDecoder, dictionary, undefined, 0);
-      dictionary = convert(dictionary, columnDecoder);
+      const { data } = readPage(reader, header, columnDecoder, dictionary, undefined, 0);
+      if (data)
+        dictionary = convert(data, columnDecoder);
     } else {
       const lastChunkLength = lastChunk?.length || 0;
-      const values = readPage(reader, header, columnDecoder, dictionary, lastChunk, selectStart - rowCount);
-      if (lastChunk === values) {
-        rowCount += values.length - lastChunkLength;
-      } else {
+      const result = readPage(reader, header, columnDecoder, dictionary, lastChunk, selectStart - rowCount);
+      if (result.skipped) {
+        if (!chunks.length) {
+          skipped += result.skipped;
+        }
+        rowCount += result.skipped;
+      } else if (result.data && lastChunk === result.data) {
+        rowCount += result.data.length - lastChunkLength;
+      } else if (result.data && result.data.length) {
         emitLastChunk?.();
-        chunks.push(values);
-        rowCount += values.length;
-        lastChunk = values;
+        chunks.push(result.data);
+        rowCount += result.data.length;
+        lastChunk = result.data;
       }
     }
   }
   emitLastChunk?.();
-  return chunks;
+  return { data: chunks, skipped };
 }
 function readPage(reader, header, columnDecoder, dictionary, previousChunk, pageStart) {
   const { type, element, schemaPath, codec, compressors } = columnDecoder;
@@ -2133,31 +2118,34 @@ function readPage(reader, header, columnDecoder, dictionary, previousChunk, page
     if (!daph)
       throw new Error("parquet data page header is undefined");
     if (pageStart > daph.num_values && isFlatColumn(schemaPath)) {
-      return new Array(daph.num_values);
+      return { skipped: daph.num_values };
     }
     const page = decompressPage(compressedBytes, Number(header.uncompressed_page_size), codec, compressors);
     const { definitionLevels, repetitionLevels, dataPage } = readDataPage(page, daph, columnDecoder);
     const values = convertWithDictionary(dataPage, dictionary, daph.encoding, columnDecoder);
     const output = Array.isArray(previousChunk) ? previousChunk : [];
-    return assembleLists(output, definitionLevels, repetitionLevels, values, schemaPath);
+    const assembled = assembleLists(output, definitionLevels, repetitionLevels, values, schemaPath);
+    return { skipped: 0, data: assembled };
   } else if (header.type === "DATA_PAGE_V2") {
     const daph2 = header.data_page_header_v2;
     if (!daph2)
       throw new Error("parquet data page header v2 is undefined");
     if (pageStart > daph2.num_rows) {
-      return new Array(daph2.num_values);
+      return { skipped: daph2.num_values };
     }
     const { definitionLevels, repetitionLevels, dataPage } = readDataPageV2(compressedBytes, header, columnDecoder);
     const values = convertWithDictionary(dataPage, dictionary, daph2.encoding, columnDecoder);
     const output = Array.isArray(previousChunk) ? previousChunk : [];
-    return assembleLists(output, definitionLevels, repetitionLevels, values, schemaPath);
+    const assembled = assembleLists(output, definitionLevels, repetitionLevels, values, schemaPath);
+    return { skipped: 0, data: assembled };
   } else if (header.type === "DICTIONARY_PAGE") {
     const diph = header.dictionary_page_header;
     if (!diph)
       throw new Error("parquet dictionary page header is undefined");
     const page = decompressPage(compressedBytes, Number(header.uncompressed_page_size), codec, compressors);
     const reader2 = { view: new DataView(page.buffer, page.byteOffset, page.byteLength), offset: 0 };
-    return readPlain(reader2, type, diph.num_values, element.type_length);
+    const dictArray = readPlain(reader2, type, diph.num_values, element.type_length);
+    return { skipped: 0, data: dictArray };
   } else {
     throw new Error(`parquet unsupported page type: ${header.type}`);
   }
@@ -2233,10 +2221,7 @@ function readRowGroup(options, { metadata }, groupPlan) {
         pathInSchema: columnMetadata.path_in_schema,
         data: Promise.resolve(file.slice(chunkPlan.range.startByte, chunkPlan.range.endByte)).then((buffer) => {
           const reader = { view: new DataView(buffer), offset: 0 };
-          return {
-            pageSkip: 0,
-            data: readColumn(reader, groupPlan, columnDecoder, options.onPage)
-          };
+          return readColumn(reader, groupPlan, columnDecoder, options.onPage);
         })
       });
       continue;
@@ -2249,7 +2234,7 @@ function readRowGroup(options, { metadata }, groupPlan) {
         const pages = offsetIndex.page_locations;
         let startByte = NaN;
         let endByte = NaN;
-        let pageSkip = 0;
+        let skipped = 0;
         for (let i = 0;i < pages.length; i++) {
           const page = pages[i];
           const pageStart = Number(page.first_row_index);
@@ -2257,22 +2242,23 @@ function readRowGroup(options, { metadata }, groupPlan) {
           if (pageStart < selectEnd && pageEnd > selectStart) {
             if (Number.isNaN(startByte)) {
               startByte = Number(page.offset);
-              pageSkip = pageStart;
+              skipped = pageStart;
             }
             endByte = Number(page.offset) + page.compressed_page_size;
           }
         }
         const buffer = await file.slice(startByte, endByte);
         const reader = { view: new DataView(buffer), offset: 0 };
-        const adjustedGroupPlan = pageSkip ? {
+        const adjustedGroupPlan = skipped ? {
           ...groupPlan,
-          groupStart: groupPlan.groupStart + pageSkip,
-          selectStart: groupPlan.selectStart - pageSkip,
-          selectEnd: groupPlan.selectEnd - pageSkip
+          groupStart: groupPlan.groupStart + skipped,
+          selectStart: groupPlan.selectStart - skipped,
+          selectEnd: groupPlan.selectEnd - skipped
         } : groupPlan;
+        const { data, skipped: columnSkipped } = readColumn(reader, adjustedGroupPlan, columnDecoder, options.onPage);
         return {
-          data: readColumn(reader, adjustedGroupPlan, columnDecoder, options.onPage),
-          pageSkip
+          data,
+          skipped: skipped + columnSkipped
         };
       })
     });
@@ -2297,8 +2283,8 @@ async function asyncGroupToRows({ asyncColumns }, selectStart, selectEnd, column
       const row = selectStart + selectRow;
       const rowData = {};
       for (let i = 0;i < asyncColumns.length; i++) {
-        const { data, pageSkip } = asyncPages[i];
-        rowData[asyncColumns[i].pathInSchema[0]] = data[row - pageSkip];
+        const { data, skipped } = asyncPages[i];
+        rowData[asyncColumns[i].pathInSchema[0]] = data[row - skipped];
       }
       groupData2[selectRow] = rowData;
     }
@@ -2311,8 +2297,8 @@ async function asyncGroupToRows({ asyncColumns }, selectStart, selectEnd, column
     for (let i = 0;i < columnOrder.length; i++) {
       const colIdx = columnIndexes[i];
       if (colIdx >= 0) {
-        const { data, pageSkip } = asyncPages[colIdx];
-        rowData[i] = data[row - pageSkip];
+        const { data, skipped } = asyncPages[colIdx];
+        rowData[i] = data[row - skipped];
       }
     }
     groupData[selectRow] = rowData;
@@ -2338,7 +2324,7 @@ function assembleAsync(asyncRowGroup, schemaTree2, parsers) {
         const flatColumn = flatData.get(child.path.join("."));
         if (!flatColumn)
           throw new Error("parquet column data not assembled");
-        return { data: [flatColumn], pageSkip: 0 };
+        return { data: [flatColumn], skipped: 0 };
       });
       assembled.push({ pathInSchema: child.path, data });
     } else {
@@ -2389,8 +2375,8 @@ async function parquetRead(options) {
   if (onChunk) {
     for (const asyncGroup of assembled) {
       for (const asyncColumn of asyncGroup.asyncColumns) {
-        asyncColumn.data.then(({ data, pageSkip }) => {
-          let rowStart2 = asyncGroup.groupStart + pageSkip;
+        asyncColumn.data.then(({ data, skipped }) => {
+          let rowStart2 = asyncGroup.groupStart + skipped;
           for (const columnData of data) {
             onChunk({
               columnName: asyncColumn.pathInSchema[0],
@@ -3976,6 +3962,108 @@ ByteWriter.prototype.appendZigZag = function(value) {
   }
 };
 
+// node_modules/hyparquet-writer/node_modules/hyparquet/src/schema.js
+function schemaTree2(schema, rootIndex, path) {
+  const element = schema[rootIndex];
+  const children = [];
+  let count = 1;
+  if (element.num_children) {
+    while (children.length < element.num_children) {
+      const childElement = schema[rootIndex + count];
+      const child = schemaTree2(schema, rootIndex + count, [...path, childElement.name]);
+      count += child.count;
+      children.push(child);
+    }
+  }
+  return { count, element, children, path };
+}
+function getSchemaPath2(schema, name) {
+  let tree = schemaTree2(schema, 0, []);
+  const path = [tree];
+  for (const part of name) {
+    const child = tree.children.find((child2) => child2.element.name === part);
+    if (!child)
+      throw new Error(`parquet schema element not found: ${name}`);
+    path.push(child);
+    tree = child;
+  }
+  return path;
+}
+
+// node_modules/hyparquet-writer/node_modules/hyparquet/src/constants.js
+var ParquetTypes2 = [
+  "BOOLEAN",
+  "INT32",
+  "INT64",
+  "INT96",
+  "FLOAT",
+  "DOUBLE",
+  "BYTE_ARRAY",
+  "FIXED_LEN_BYTE_ARRAY"
+];
+var Encodings2 = [
+  "PLAIN",
+  "GROUP_VAR_INT",
+  "PLAIN_DICTIONARY",
+  "RLE",
+  "BIT_PACKED",
+  "DELTA_BINARY_PACKED",
+  "DELTA_LENGTH_BYTE_ARRAY",
+  "DELTA_BYTE_ARRAY",
+  "RLE_DICTIONARY",
+  "BYTE_STREAM_SPLIT"
+];
+var FieldRepetitionTypes2 = [
+  "REQUIRED",
+  "OPTIONAL",
+  "REPEATED"
+];
+var ConvertedTypes2 = [
+  "UTF8",
+  "MAP",
+  "MAP_KEY_VALUE",
+  "LIST",
+  "ENUM",
+  "DECIMAL",
+  "DATE",
+  "TIME_MILLIS",
+  "TIME_MICROS",
+  "TIMESTAMP_MILLIS",
+  "TIMESTAMP_MICROS",
+  "UINT_8",
+  "UINT_16",
+  "UINT_32",
+  "UINT_64",
+  "INT_8",
+  "INT_16",
+  "INT_32",
+  "INT_64",
+  "JSON",
+  "BSON",
+  "INTERVAL"
+];
+var CompressionCodecs2 = [
+  "UNCOMPRESSED",
+  "SNAPPY",
+  "GZIP",
+  "LZO",
+  "BROTLI",
+  "LZ4",
+  "ZSTD",
+  "LZ4_RAW"
+];
+var PageTypes2 = [
+  "DATA_PAGE",
+  "INDEX_PAGE",
+  "DICTIONARY_PAGE",
+  "DATA_PAGE_V2"
+];
+var BoundaryOrders = [
+  "UNORDERED",
+  "ASCENDING",
+  "DESCENDING"
+];
+
 // node_modules/hyparquet-writer/src/delta.js
 var BLOCK_SIZE = 128;
 var MINIBLOCKS_PER_BLOCK = 4;
@@ -4451,6 +4539,24 @@ function bigIntArray(values) {
   throw new Error("Expected bigint array for BYTE_STREAM_SPLIT encoding");
 }
 
+// node_modules/hyparquet-writer/node_modules/hyparquet/src/thrift.js
+var CompactType2 = {
+  STOP: 0,
+  TRUE: 1,
+  FALSE: 2,
+  BYTE: 3,
+  I16: 4,
+  I32: 5,
+  I64: 6,
+  DOUBLE: 7,
+  BINARY: 8,
+  LIST: 9,
+  SET: 10,
+  MAP: 11,
+  STRUCT: 12,
+  UUID: 13
+};
+
 // node_modules/hyparquet-writer/src/thrift.js
 function serializeTCompactProtocol(writer, data) {
   let lastFid = 0;
@@ -4475,55 +4581,55 @@ function serializeTCompactProtocol(writer, data) {
     writeElement(writer, type, value);
     lastFid = fid;
   }
-  writer.appendUint8(CompactType.STOP);
+  writer.appendUint8(CompactType2.STOP);
 }
 function getCompactTypeForValue(value) {
   if (value === true)
-    return CompactType.TRUE;
+    return CompactType2.TRUE;
   if (value === false)
-    return CompactType.FALSE;
+    return CompactType2.FALSE;
   if (Number.isInteger(value))
-    return CompactType.I32;
+    return CompactType2.I32;
   if (typeof value === "number")
-    return CompactType.DOUBLE;
+    return CompactType2.DOUBLE;
   if (typeof value === "bigint")
-    return CompactType.I64;
+    return CompactType2.I64;
   if (typeof value === "string")
-    return CompactType.BINARY;
+    return CompactType2.BINARY;
   if (value instanceof Uint8Array)
-    return CompactType.BINARY;
+    return CompactType2.BINARY;
   if (Array.isArray(value))
-    return CompactType.LIST;
+    return CompactType2.LIST;
   if (value && typeof value === "object")
-    return CompactType.STRUCT;
+    return CompactType2.STRUCT;
   throw new Error(`Cannot determine thrift compact type for: ${value}`);
 }
 function writeElement(writer, type, value) {
-  if (type === CompactType.TRUE)
+  if (type === CompactType2.TRUE)
     return;
-  if (type === CompactType.FALSE)
+  if (type === CompactType2.FALSE)
     return;
-  if (type === CompactType.BYTE && typeof value === "number") {
+  if (type === CompactType2.BYTE && typeof value === "number") {
     writer.appendUint8(value);
-  } else if (type === CompactType.I32 && typeof value === "number") {
+  } else if (type === CompactType2.I32 && typeof value === "number") {
     const zigzag = value << 1 ^ value >> 31;
     writer.appendVarInt(zigzag);
-  } else if (type === CompactType.I64 && typeof value === "bigint") {
+  } else if (type === CompactType2.I64 && typeof value === "bigint") {
     const zigzag = value << 1n ^ value >> 63n;
     writer.appendVarBigInt(zigzag);
-  } else if (type === CompactType.DOUBLE && typeof value === "number") {
+  } else if (type === CompactType2.DOUBLE && typeof value === "number") {
     writer.appendFloat64(value);
-  } else if (type === CompactType.BINARY && typeof value === "string") {
+  } else if (type === CompactType2.BINARY && typeof value === "string") {
     const bytes = new TextEncoder().encode(value);
     writer.appendVarInt(bytes.length);
     writer.appendBytes(bytes);
-  } else if (type === CompactType.BINARY && value instanceof Uint8Array) {
+  } else if (type === CompactType2.BINARY && value instanceof Uint8Array) {
     writer.appendVarInt(value.byteLength);
     writer.appendBytes(value);
-  } else if (type === CompactType.LIST && Array.isArray(value)) {
+  } else if (type === CompactType2.LIST && Array.isArray(value)) {
     const size = value.length;
     if (size === 0) {
-      writer.appendUint8(0 << 4 | CompactType.BYTE);
+      writer.appendUint8(0 << 4 | CompactType2.BYTE);
       return;
     }
     const elemType = getCompactTypeForValue(value[0]);
@@ -4532,7 +4638,7 @@ function writeElement(writer, type, value) {
     if (size > 14) {
       writer.appendVarInt(size);
     }
-    if (elemType === CompactType.TRUE || elemType === CompactType.FALSE) {
+    if (elemType === CompactType2.TRUE || elemType === CompactType2.FALSE) {
       for (const v of value) {
         writer.appendUint8(v ? 1 : 0);
       }
@@ -4541,7 +4647,7 @@ function writeElement(writer, type, value) {
         writeElement(writer, elemType, v);
       }
     }
-  } else if (type === CompactType.STRUCT && typeof value === "object") {
+  } else if (type === CompactType2.STRUCT && typeof value === "object") {
     let lastFid = 0;
     for (const [k, v] of Object.entries(value)) {
       if (v === undefined)
@@ -4564,7 +4670,7 @@ function writeElement(writer, type, value) {
       writeElement(writer, t, v);
       lastFid = fid;
     }
-    writer.appendUint8(CompactType.STOP);
+    writer.appendUint8(CompactType2.STOP);
   } else {
     throw new Error(`unhandled type in writeElement: ${type} for value ${value}`);
   }
@@ -4646,25 +4752,25 @@ function writeDataPageV2({ writer, values, column, encoding, pageData }) {
 }
 function writePageHeader(writer, header) {
   const compact = {
-    field_1: PageTypes.indexOf(header.type),
+    field_1: PageTypes2.indexOf(header.type),
     field_2: header.uncompressed_page_size,
     field_3: header.compressed_page_size,
     field_4: header.crc,
     field_5: header.data_page_header && {
       field_1: header.data_page_header.num_values,
-      field_2: Encodings.indexOf(header.data_page_header.encoding),
-      field_3: Encodings.indexOf(header.data_page_header.definition_level_encoding),
-      field_4: Encodings.indexOf(header.data_page_header.repetition_level_encoding)
+      field_2: Encodings2.indexOf(header.data_page_header.encoding),
+      field_3: Encodings2.indexOf(header.data_page_header.definition_level_encoding),
+      field_4: Encodings2.indexOf(header.data_page_header.repetition_level_encoding)
     },
     field_7: header.dictionary_page_header && {
       field_1: header.dictionary_page_header.num_values,
-      field_2: Encodings.indexOf(header.dictionary_page_header.encoding)
+      field_2: Encodings2.indexOf(header.dictionary_page_header.encoding)
     },
     field_8: header.data_page_header_v2 && {
       field_1: header.data_page_header_v2.num_values,
       field_2: header.data_page_header_v2.num_nulls,
       field_3: header.data_page_header_v2.num_rows,
-      field_4: Encodings.indexOf(header.data_page_header_v2.encoding),
+      field_4: Encodings2.indexOf(header.data_page_header_v2.encoding),
       field_5: header.data_page_header_v2.definition_levels_byte_length,
       field_6: header.data_page_header_v2.repetition_levels_byte_length,
       field_7: header.data_page_header_v2.is_compressed ? undefined : false
@@ -4798,6 +4904,31 @@ function inferCoordinateDimensions(value) {
   return maxDim || 2;
 }
 
+// node_modules/hyparquet-writer/node_modules/hyparquet/src/utils.js
+function toJson(obj) {
+  if (obj === undefined)
+    return null;
+  if (typeof obj === "bigint")
+    return Number(obj);
+  if (Object.is(obj, -0))
+    return 0;
+  if (Array.isArray(obj))
+    return obj.map(toJson);
+  if (obj instanceof Uint8Array)
+    return Array.from(obj);
+  if (obj instanceof Date)
+    return obj.toISOString();
+  if (obj instanceof Object) {
+    const newObj = {};
+    for (const key of Object.keys(obj)) {
+      if (obj[key] === undefined)
+        continue;
+      newObj[key] = toJson(obj[key]);
+    }
+    return newObj;
+  }
+  return obj;
+}
 // node_modules/hyparquet-writer/src/wkb.js
 function geojsonToWkb(geometry) {
   const writer = new ByteWriter;
@@ -5608,12 +5739,12 @@ function writeMetadata(writer, metadata) {
   const compact = {
     field_1: metadata.version,
     field_2: metadata.schema && metadata.schema.map((element) => ({
-      field_1: element.type && ParquetTypes.indexOf(element.type),
+      field_1: element.type && ParquetTypes2.indexOf(element.type),
       field_2: element.type_length,
-      field_3: element.repetition_type && FieldRepetitionTypes.indexOf(element.repetition_type),
+      field_3: element.repetition_type && FieldRepetitionTypes2.indexOf(element.repetition_type),
       field_4: element.name,
       field_5: element.num_children,
-      field_6: element.converted_type && ConvertedTypes.indexOf(element.converted_type),
+      field_6: element.converted_type && ConvertedTypes2.indexOf(element.converted_type),
       field_7: element.scale,
       field_8: element.precision,
       field_9: element.field_id,
@@ -5625,10 +5756,10 @@ function writeMetadata(writer, metadata) {
         field_1: c.file_path,
         field_2: c.file_offset,
         field_3: c.meta_data && {
-          field_1: ParquetTypes.indexOf(c.meta_data.type),
-          field_2: c.meta_data.encodings.map((e) => Encodings.indexOf(e)),
+          field_1: ParquetTypes2.indexOf(c.meta_data.type),
+          field_2: c.meta_data.encodings.map((e) => Encodings2.indexOf(e)),
           field_3: c.meta_data.path_in_schema,
-          field_4: CompressionCodecs.indexOf(c.meta_data.codec),
+          field_4: CompressionCodecs2.indexOf(c.meta_data.codec),
           field_5: c.meta_data.num_values,
           field_6: c.meta_data.total_uncompressed_size,
           field_7: c.meta_data.total_compressed_size,
@@ -5641,8 +5772,8 @@ function writeMetadata(writer, metadata) {
           field_11: c.meta_data.dictionary_page_offset,
           field_12: c.meta_data.statistics && unconvertStatistics(c.meta_data.statistics, schemaElement(metadata.schema, c.meta_data.path_in_schema, columnIndex + 1)),
           field_13: c.meta_data.encoding_stats && c.meta_data.encoding_stats.map((es) => ({
-            field_1: PageTypes.indexOf(es.page_type),
-            field_2: Encodings.indexOf(es.encoding),
+            field_1: PageTypes2.indexOf(es.page_type),
+            field_2: Encodings2.indexOf(es.encoding),
             field_3: es.count
           })),
           field_14: c.meta_data.bloom_filter_offset,
@@ -5695,7 +5826,7 @@ function writeMetadata(writer, metadata) {
 }
 function schemaElement(schema, path, fallbackIndex) {
   if (path?.length) {
-    const resolved = getSchemaPath(schema, path).at(-1)?.element;
+    const resolved = getSchemaPath2(schema, path).at(-1)?.element;
     if (resolved)
       return resolved;
   }
@@ -5933,7 +6064,7 @@ ParquetWriter.prototype.write = function({ columnData, rowGroupSize = [100, 1000
     for (let j = 0;j < columnData.length; j++) {
       const { name, data, encoding, columnIndex = false, offsetIndex = false } = columnData[j];
       const groupData = data.slice(groupStartIndex, groupStartIndex + groupSize);
-      const schemaTreePath = getSchemaPath(this.schema, [name]);
+      const schemaTreePath = getSchemaPath2(this.schema, [name]);
       const leafPaths = getLeafSchemaPaths(schemaTreePath);
       const columnNode = schemaTreePath.at(-1);
       const normalizedData = columnNode ? Array.from(groupData, (row) => normalizeValue(columnNode, row)) : Array.from(groupData);
@@ -6088,6 +6219,9 @@ var BASE_DELAY_MS = 1000;
 var BACKOFF_FACTOR = 2;
 var JITTER_RANGE = 0.25;
 var BATCH_SIZE = 100;
+function formatError(error) {
+  return error instanceof Error ? error.toString() : String(error);
+}
 function decompressPagefind(data) {
   const decompressed = gunzipSync(Buffer.from(data));
   if (decompressed.length < PAGEFIND_HEADER_SIZE) {
@@ -6144,7 +6278,9 @@ async function fetchAndParseMeta(langHash) {
     decoded = decode2(decompressed);
   } catch (error) {
     const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`Failed to decode pf_meta: ${detail}. The Pagefind binary format may have changed.`);
+    throw new Error(`Failed to decode pf_meta: ${detail}. The Pagefind binary format may have changed.`, {
+      cause: error
+    });
   }
   if (!Array.isArray(decoded) || !Array.isArray(decoded[1])) {
     throw new Error("Failed to decode pf_meta: unexpected structure. The Pagefind binary format may have changed.");
@@ -6176,10 +6312,10 @@ async function withConcurrencyLimit(tasks, limit) {
   let running = 0;
   let index = 0;
   let completed = 0;
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     function next() {
       if (completed === tasks.length) {
-        resolve(results);
+        resolve2(results);
         return;
       }
       while (running < limit && index < tasks.length) {
@@ -6202,8 +6338,11 @@ async function withConcurrencyLimit(tasks, limit) {
     next();
   });
 }
-async function fetchAllDocs(dbPath) {
+async function fetchAllDocs(dbPath, options = {}) {
   const entry = await fetchEntryPoint();
+  const onProgress = options.onProgress;
+  const concurrency = typeof options.concurrency === "number" && options.concurrency > 0 ? options.concurrency : DEFAULT_CONCURRENCY;
+  const progressEvery = typeof options.progressEvery === "number" && options.progressEvery > 0 ? Math.floor(options.progressEvery) : BATCH_SIZE;
   const langKey = Object.keys(entry.languages)[0];
   if (!langKey) {
     throw new Error("No languages found in Pagefind entry");
@@ -6211,17 +6350,25 @@ async function fetchAllDocs(dbPath) {
   const langHash = entry.languages[langKey].hash;
   const pageHashes = await fetchAndParseMeta(langHash);
   const totalPages = pageHashes.length;
+  onProgress?.({ type: "discovered", totalPages });
   const fetchedRecords = [];
   const failedUrls = [];
-  let done = 0;
-  const tasks = pageHashes.map((hash) => () => fetchFragment(hash).then((record) => {
-    done++;
-    if (done % BATCH_SIZE === 0 || done === totalPages) {
-      console.log(`Fetched ${done}/${totalPages} pages...`);
+  let processedPages = 0;
+  const tasks = pageHashes.map((hash) => () => fetchFragment(hash).catch((error) => {
+    const url = `${PAGEFIND_BASE}/fragment/${hash}.pf_fragment`;
+    onProgress?.({
+      type: "page-failed",
+      url,
+      error: formatError(error)
+    });
+    throw error;
+  }).finally(() => {
+    processedPages += 1;
+    if (processedPages % progressEvery === 0 || processedPages === totalPages) {
+      onProgress?.({ type: "progress", processedPages, totalPages });
     }
-    return record;
   }));
-  const results = await withConcurrencyLimit(tasks, DEFAULT_CONCURRENCY);
+  const results = await withConcurrencyLimit(tasks, concurrency);
   for (let i = 0;i < results.length; i++) {
     const result = results[i];
     if (result.status === "fulfilled") {
@@ -6229,10 +6376,15 @@ async function fetchAllDocs(dbPath) {
     } else {
       const url = `${PAGEFIND_BASE}/fragment/${pageHashes[i]}.pf_fragment`;
       failedUrls.push(url);
-      console.log(`[ERROR] Failed to fetch ${url}: ${result.reason.message}`);
     }
   }
   await writeParquet(fetchedRecords, dbPath);
+  onProgress?.({
+    type: "completed",
+    totalPages,
+    fetchedPages: fetchedRecords.length,
+    failedPages: failedUrls.length
+  });
   return {
     totalPages,
     fetchedPages: fetchedRecords.length,
@@ -6241,70 +6393,243 @@ async function fetchAllDocs(dbPath) {
   };
 }
 
+// src/docs/snapshot.ts
+import fs from "fs/promises";
+import path from "path";
+var DEFAULT_DOCS_SNAPSHOT_URLS = [
+  "https://raw.githubusercontent.com/anand-testcompare/opencode-palantir/main/data/docs.parquet"
+];
+var MIN_SNAPSHOT_BYTES = 64;
+var inFlightByPath = new Map;
+function formatError2(err) {
+  return err instanceof Error ? err.toString() : String(err);
+}
+function emit(onEvent, event) {
+  if (!onEvent)
+    return;
+  onEvent(event);
+}
+function normalizeSnapshotUrls(customUrls) {
+  const envSingleRaw = process.env.OPENCODE_PALANTIR_DOCS_SNAPSHOT_URL;
+  const envManyRaw = process.env.OPENCODE_PALANTIR_DOCS_SNAPSHOT_URLS;
+  const envSingle = typeof envSingleRaw === "string" && envSingleRaw.trim().length > 0 ? [envSingleRaw.trim()] : [];
+  const envMany = typeof envManyRaw === "string" && envManyRaw.trim().length > 0 ? envManyRaw.split(",").map((x) => x.trim()).filter((x) => x.length > 0) : [];
+  const resolved = customUrls ?? [...envMany, ...envSingle, ...DEFAULT_DOCS_SNAPSHOT_URLS];
+  return Array.from(new Set(resolved));
+}
+async function ensureDirectoryExists(dbPath) {
+  await fs.mkdir(path.dirname(dbPath), { recursive: true });
+}
+async function statIfExists(filePath) {
+  try {
+    return await fs.stat(filePath);
+  } catch (err) {
+    if (err.code === "ENOENT")
+      return null;
+    throw err;
+  }
+}
+function assertValidSnapshotSize(bytes, source) {
+  if (bytes < MIN_SNAPSHOT_BYTES) {
+    throw new Error(`Snapshot from ${source} is unexpectedly small (${bytes} bytes). Expected at least ${MIN_SNAPSHOT_BYTES} bytes.`);
+  }
+}
+function tempPathFor(dbPath) {
+  const base = path.basename(dbPath);
+  return path.join(path.dirname(dbPath), `.${base}.tmp.${process.pid}.${Date.now()}`);
+}
+async function writeBufferAtomic(dbPath, bytes) {
+  const tmp = tempPathFor(dbPath);
+  await fs.writeFile(tmp, bytes);
+  await fs.rename(tmp, dbPath);
+}
+async function copyFileAtomic(sourcePath, dbPath) {
+  const tmp = tempPathFor(dbPath);
+  await fs.copyFile(sourcePath, tmp);
+  await fs.rename(tmp, dbPath);
+}
+function bundledSnapshotCandidates(dbPath, pluginDirectory) {
+  const candidates = [];
+  if (pluginDirectory && pluginDirectory.trim().length > 0) {
+    candidates.push(path.resolve(pluginDirectory, "data", "docs.parquet"));
+  } else {
+    candidates.push(path.resolve(import.meta.dir, "..", "..", "data", "docs.parquet"));
+  }
+  const target = path.resolve(dbPath);
+  const deduped = Array.from(new Set(candidates.map((x) => path.resolve(x))));
+  return deduped.filter((candidate) => candidate !== target);
+}
+async function tryDownloadSnapshot(dbPath, urls, onEvent) {
+  const errors = [];
+  for (const url of urls) {
+    emit(onEvent, { type: "download-start", url });
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        const reason = `HTTP ${response.status} ${response.statusText}`.trim();
+        emit(onEvent, { type: "download-failed", url, error: reason });
+        errors.push(`${url}: ${reason}`);
+        continue;
+      }
+      const bytes = new Uint8Array(await response.arrayBuffer());
+      assertValidSnapshotSize(bytes.byteLength, url);
+      await writeBufferAtomic(dbPath, bytes);
+      emit(onEvent, { type: "download-success", url, bytes: bytes.byteLength });
+      return {
+        dbPath,
+        changed: true,
+        source: "download",
+        bytes: bytes.byteLength,
+        downloadUrl: url
+      };
+    } catch (err) {
+      const reason = formatError2(err);
+      emit(onEvent, { type: "download-failed", url, error: reason });
+      errors.push(`${url}: ${reason}`);
+    }
+  }
+  if (errors.length === 0)
+    return null;
+  throw new Error([
+    "Unable to download prebuilt docs snapshot from configured source URLs.",
+    ...errors.map((line) => `- ${line}`)
+  ].join(`
+`));
+}
+async function tryCopyBundledSnapshot(dbPath, pluginDirectory, onEvent) {
+  const candidates = bundledSnapshotCandidates(dbPath, pluginDirectory);
+  for (const sourcePath of candidates) {
+    const stat = await statIfExists(sourcePath);
+    if (!stat || !stat.isFile())
+      continue;
+    emit(onEvent, { type: "copy-start", sourcePath });
+    assertValidSnapshotSize(stat.size, sourcePath);
+    await copyFileAtomic(sourcePath, dbPath);
+    emit(onEvent, { type: "copy-success", sourcePath, bytes: stat.size });
+    return {
+      dbPath,
+      changed: true,
+      source: "bundled-copy",
+      bytes: stat.size
+    };
+  }
+  return null;
+}
+async function ensureDocsParquetInternal(options) {
+  const dbPath = path.resolve(options.dbPath);
+  const force = options.force === true;
+  const onEvent = options.onEvent;
+  emit(onEvent, { type: "start", force });
+  await ensureDirectoryExists(dbPath);
+  if (!force) {
+    const existing = await statIfExists(dbPath);
+    if (existing && existing.isFile()) {
+      assertValidSnapshotSize(existing.size, dbPath);
+      const result = {
+        dbPath,
+        changed: false,
+        source: "existing",
+        bytes: existing.size
+      };
+      emit(onEvent, { type: "skip-existing", bytes: existing.size });
+      emit(onEvent, { type: "done", result });
+      return result;
+    }
+  }
+  const snapshotUrls = normalizeSnapshotUrls(options.snapshotUrls);
+  let downloadError = null;
+  try {
+    const downloaded = await tryDownloadSnapshot(dbPath, snapshotUrls, onEvent);
+    if (downloaded) {
+      emit(onEvent, { type: "done", result: downloaded });
+      return downloaded;
+    }
+  } catch (err) {
+    downloadError = err instanceof Error ? err : new Error(String(err));
+  }
+  const copied = await tryCopyBundledSnapshot(dbPath, options.pluginDirectory, onEvent);
+  if (copied) {
+    emit(onEvent, { type: "done", result: copied });
+    return copied;
+  }
+  const fallbackHint = "No bundled snapshot was found. You can run /refresh-docs-rescrape as a fallback.";
+  if (downloadError) {
+    throw new Error(`${downloadError.message}
+${fallbackHint}`);
+  }
+  throw new Error(`No docs snapshot sources were available. ${fallbackHint} ` + `Checked URLs=${snapshotUrls.length}, bundled candidates=${bundledSnapshotCandidates(dbPath, options.pluginDirectory).length}.`);
+}
+async function ensureDocsParquet(options) {
+  const dbPath = path.resolve(options.dbPath);
+  const existing = inFlightByPath.get(dbPath);
+  if (existing)
+    return existing;
+  let promise;
+  promise = ensureDocsParquetInternal({ ...options, dbPath }).finally(() => {
+    if (inFlightByPath.get(dbPath) === promise) {
+      inFlightByPath.delete(dbPath);
+    }
+  });
+  inFlightByPath.set(dbPath, promise);
+  return promise;
+}
+
 // src/palantir-mcp/commands.ts
-import path3 from "path";
+import path4 from "path";
 
 // src/palantir-mcp/allowlist.ts
-function isMutatingTool(toolName) {
-  const re = /(?:^|[_-])(create|update|delete|remove|set|write|put|post|patch|deploy|publish|commit|run|execute|trigger|start|stop|cancel|schedule|grant|revoke|upload|import|export)(?:$|[_-])/i;
-  return re.test(toolName);
-}
-function isReadOnlyTool(toolName) {
-  const re = /(?:^|[_-])(get|list|search|query|describe|read|fetch|inspect|schema|metadata|lineage|preview|validate|diff)(?:$|[_-])/i;
-  return re.test(toolName);
-}
 function matchesAny(toolName, patterns) {
   return patterns.some((p) => p.test(toolName));
 }
+var LIBRARIAN_MUTATION_DENY = [
+  /(?:^|[_-])(create|update|delete|remove|set|write|put|post|patch|deploy|publish|commit|run|execute|trigger|start|stop|cancel|schedule|grant|revoke|upload|import|export|connect|convert|install|clone|close|replace|abort)(?:$|[_-])/i
+];
+var FOUNDRY_DISCOVERY_DENY = [
+  /documentation/i,
+  /(?:^|[_-])search_foundry_(documentation|ontology|functions)(?:$|[_-])/i,
+  /(?:^|[_-])list_platform_sdk_apis(?:$|[_-])/i,
+  /(?:^|[_-])get_platform_sdk_api_reference(?:$|[_-])/i,
+  /(?:^|[_-])get_ontology_sdk_(context|examples)(?:$|[_-])/i,
+  /(?:^|[_-])view_osdk_definition(?:$|[_-])/i
+];
+var PROFILE_POLICIES = {
+  pipelines_transforms: {
+    librarianDeny: [...LIBRARIAN_MUTATION_DENY],
+    foundryDeny: [
+      ...FOUNDRY_DISCOVERY_DENY,
+      /(?:^|[_-])(convert_to_osdk_react|install_sdk_package|generate_new_ontology_sdk_version)(?:$|[_-])/i
+    ]
+  },
+  osdk_functions_ts: {
+    librarianDeny: [...LIBRARIAN_MUTATION_DENY],
+    foundryDeny: [
+      ...FOUNDRY_DISCOVERY_DENY,
+      /(?:^|[_-])(create_python_transforms_code_repository|get_python_transforms_documentation)(?:$|[_-])/i
+    ]
+  },
+  default: {
+    librarianDeny: [...LIBRARIAN_MUTATION_DENY],
+    foundryDeny: [...FOUNDRY_DISCOVERY_DENY]
+  }
+};
 function computeAllowedTools(profile, toolNames) {
   const uniqueSortedTools = Array.from(new Set(toolNames)).sort((a, b) => a.localeCompare(b));
+  const policy = PROFILE_POLICIES[profile];
   const librarianAllow = new Set;
-  const pipelinesBoost = [
-    /pipeline/i,
-    /transform/i,
-    /job/i,
-    /dataset/i,
-    /ontology/i,
-    /object/i,
-    /action/i,
-    /lineage/i,
-    /schema/i,
-    /preview/i
-  ];
-  const osdkBoost = [
-    /osdk/i,
-    /function/i,
-    /artifact/i,
-    /package/i,
-    /release/i,
-    /deploy/i
-  ];
+  const foundryAllow = new Set;
   for (const name of uniqueSortedTools) {
-    if (isMutatingTool(name))
-      continue;
-    if (profile === "all") {
-      librarianAllow.add(name);
-      continue;
-    }
-    if (isReadOnlyTool(name)) {
+    if (!matchesAny(name, policy.librarianDeny)) {
       librarianAllow.add(name);
-      continue;
-    }
-    if (profile === "pipelines_transforms" && matchesAny(name, pipelinesBoost)) {
-      librarianAllow.add(name);
-      continue;
     }
-    if (profile === "osdk_functions_ts" && matchesAny(name, osdkBoost)) {
-      librarianAllow.add(name);
-      continue;
+    if (!matchesAny(name, policy.foundryDeny)) {
+      foundryAllow.add(name);
     }
   }
-  const foundryAllow = new Set(librarianAllow);
   return { librarianAllow, foundryAllow };
 }
 
 // src/palantir-mcp/mcp-client.ts
-function formatError(err) {
+function formatError3(err) {
   return err instanceof Error ? err.toString() : String(err);
 }
 function withTimeout(p, ms, label) {
@@ -6421,8 +6746,8 @@ ${errText}`));
     const req = { jsonrpc: "2.0", id, method, params };
     const line = `${JSON.stringify(req)}
 `;
-    const p = new Promise((resolve, reject) => {
-      pending.set(id, { resolve, reject });
+    const p = new Promise((resolve2, reject) => {
+      pending.set(id, { resolve: resolve2, reject });
     });
     await writeStdin(line);
     return p;
@@ -6445,8 +6770,10 @@ ${errText}`));
     return Array.from(new Set(names)).sort((a, b) => a.localeCompare(b));
   } catch (err) {
     const stderrText = stderrChunks.join("");
-    throw new Error(`[ERROR] Failed to list palantir-mcp tools: ${formatError(err)}
-${stderrText}`);
+    throw new Error(`[ERROR] Failed to list palantir-mcp tools: ${formatError3(err)}
+${stderrText}`, {
+      cause: err
+    });
   } finally {
     try {
       proc.kill();
@@ -6484,8 +6811,8 @@ function normalizeFoundryBaseUrl(raw) {
 }
 
 // src/palantir-mcp/opencode-config.ts
-import fs from "fs/promises";
-import path from "path";
+import fs2 from "fs/promises";
+import path2 from "path";
 
 // node_modules/jsonc-parser/lib/esm/impl/scanner.js
 function createScanner(text, ignoreTrivia = false) {
@@ -7297,28 +7624,28 @@ var OPENCODE_JSON_FILENAME = "opencode.json";
 function isRecord(value) {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
-function formatError2(err) {
+function formatError4(err) {
   return err instanceof Error ? err.toString() : String(err);
 }
 async function pathExists(p) {
   try {
-    await fs.access(p);
+    await fs2.access(p);
     return true;
   } catch {
     return false;
   }
 }
 async function readOpencodeJsonc(worktree) {
-  const configPath = path.join(worktree, OPENCODE_JSONC_FILENAME);
+  const configPath = path2.join(worktree, OPENCODE_JSONC_FILENAME);
   if (!await pathExists(configPath))
     return { ok: false, missing: true };
   let text;
   try {
-    text = await fs.readFile(configPath, "utf8");
+    text = await fs2.readFile(configPath, "utf8");
   } catch (err) {
     return {
       ok: false,
-      error: `[ERROR] Failed reading ${OPENCODE_JSONC_FILENAME}: ${formatError2(err)}`
+      error: `[ERROR] Failed reading ${OPENCODE_JSONC_FILENAME}: ${formatError4(err)}`
     };
   }
   const errors = [];
@@ -7333,16 +7660,16 @@ async function readOpencodeJsonc(worktree) {
   return { ok: true, path: configPath, text, data };
 }
 async function readLegacyOpencodeJson(worktree) {
-  const legacyPath = path.join(worktree, OPENCODE_JSON_FILENAME);
+  const legacyPath = path2.join(worktree, OPENCODE_JSON_FILENAME);
   if (!await pathExists(legacyPath))
     return { ok: false, missing: true };
   let text;
   try {
-    text = await fs.readFile(legacyPath, "utf8");
+    text = await fs2.readFile(legacyPath, "utf8");
   } catch (err) {
     return {
       ok: false,
-      error: `[ERROR] Failed reading ${OPENCODE_JSON_FILENAME}: ${formatError2(err)}`
+      error: `[ERROR] Failed reading ${OPENCODE_JSON_FILENAME}: ${formatError4(err)}`
     };
   }
   let data;
@@ -7351,7 +7678,7 @@ async function readLegacyOpencodeJson(worktree) {
   } catch (err) {
     return {
       ok: false,
-      error: `[ERROR] Failed parsing ${OPENCODE_JSON_FILENAME}: ${formatError2(err)}`
+      error: `[ERROR] Failed parsing ${OPENCODE_JSON_FILENAME}: ${formatError4(err)}`
     };
   }
   return { ok: true, path: legacyPath, text, data };
@@ -7380,24 +7707,24 @@ function mergeLegacyIntoJsonc(legacyData, jsoncData) {
   return deepMergePreferTarget(base, legacy);
 }
 async function writeFileAtomic(filePath, text) {
-  const dir = path.dirname(filePath);
-  const base = path.basename(filePath);
-  const tmp = path.join(dir, `.${base}.tmp.${process.pid}.${Date.now()}`);
-  await fs.writeFile(tmp, text, "utf8");
-  await fs.rename(tmp, filePath);
+  const dir = path2.dirname(filePath);
+  const base = path2.basename(filePath);
+  const tmp = path2.join(dir, `.${base}.tmp.${process.pid}.${Date.now()}`);
+  await fs2.writeFile(tmp, text, "utf8");
+  await fs2.rename(tmp, filePath);
 }
 async function renameLegacyToBak(worktree) {
-  const legacyPath = path.join(worktree, OPENCODE_JSON_FILENAME);
+  const legacyPath = path2.join(worktree, OPENCODE_JSON_FILENAME);
   if (!await pathExists(legacyPath))
     return null;
-  const baseBak = path.join(worktree, `${OPENCODE_JSON_FILENAME}.bak`);
+  const baseBak = path2.join(worktree, `${OPENCODE_JSON_FILENAME}.bak`);
   let bakPath = baseBak;
   let i = 1;
   while (await pathExists(bakPath)) {
     bakPath = `${baseBak}.${i}`;
     i += 1;
   }
-  await fs.rename(legacyPath, bakPath);
+  await fs2.rename(legacyPath, bakPath);
   return bakPath;
 }
 function toolKey(toolName) {
@@ -7470,9 +7797,11 @@ function ensureAgentBase(data, agentName) {
 }
 function ensureAgentDefaults(agent, agentName) {
   const defaultDescription = agentName === "foundry-librarian" ? "Foundry exploration and context gathering (parallel-friendly)" : "Foundry execution agent (uses only enabled palantir-mcp tools)";
+  const defaultMode = agentName === "foundry" ? "all" : "subagent";
   const mode = agent["mode"];
-  if (typeof mode !== "string")
-    agent["mode"] = "subagent";
+  if (mode !== "subagent" && mode !== "primary" && mode !== "all") {
+    agent["mode"] = defaultMode;
+  }
   if (typeof agent["hidden"] !== "boolean")
     agent["hidden"] = false;
   if (typeof agent["description"] !== "string") {
@@ -7637,11 +7966,11 @@ function stringifyJsonc(data) {
 }
 
 // src/palantir-mcp/repo-scan.ts
-import fs2 from "fs/promises";
-import path2 from "path";
+import fs3 from "fs/promises";
+import path3 from "path";
 async function pathExists2(p) {
   try {
-    await fs2.access(p);
+    await fs3.access(p);
     return true;
   } catch {
     return false;
@@ -7649,7 +7978,7 @@ async function pathExists2(p) {
 }
 async function readTextFileBounded(p, maxBytes) {
   try {
-    const file = await fs2.open(p, "r");
+    const file = await fs3.open(p, "r");
     try {
       const buf = Buffer.alloc(maxBytes);
       const { bytesRead } = await file.read(buf, 0, maxBytes, 0);
@@ -7661,209 +7990,120 @@ async function readTextFileBounded(p, maxBytes) {
     return null;
   }
 }
-function addScore(scores, reasons, profile, delta, reason) {
-  scores[profile] += delta;
-  reasons.push(reason);
-}
-function pickBestProfile(scores) {
-  const threshold = 3;
-  const ordered = ["all", "pipelines_transforms", "osdk_functions_ts", "unknown"];
-  let best = "unknown";
-  let bestScore = -1;
-  for (const p of ordered) {
-    const s = scores[p];
-    if (s > bestScore) {
-      best = p;
-      bestScore = s;
-    }
-  }
-  if (bestScore < threshold)
-    return "unknown";
-  return best;
-}
-async function parsePackageJson(p) {
-  const text = await readTextFileBounded(p, 200000);
-  if (!text)
+async function getPackageJson(root, context) {
+  if (context.packageJsonLoaded)
+    return context.packageJson;
+  context.packageJsonLoaded = true;
+  const packageJsonPath = path3.join(root, "package.json");
+  const text = await readTextFileBounded(packageJsonPath, 200000);
+  if (!text) {
+    context.packageJson = null;
     return null;
+  }
   try {
-    return JSON.parse(text);
+    context.packageJson = JSON.parse(text);
   } catch {
-    return null;
-  }
-}
-function getAllDependencyKeys(pkg) {
-  const deps = pkg.dependencies ?? {};
-  const dev = pkg.devDependencies ?? {};
-  const peer = pkg.peerDependencies ?? {};
-  return Object.keys({ ...deps, ...dev, ...peer });
-}
-async function collectSampleFiles(root, limit) {
-  const ignoreDirs = new Set([
-    ".git",
-    "node_modules",
-    "dist",
-    ".opencode",
-    "data",
-    ".memory",
-    ".sisyphus",
-    ".zed",
-    ".mise",
-    "coverage",
-    "build"
-  ]);
-  const allowedExts = new Set([
-    ".md",
-    ".ts",
-    ".js",
-    ".py",
-    ".yaml",
-    ".yml",
-    ".toml",
-    ".json"
-  ]);
-  const results = [];
-  const queue = [root];
-  const maxDirs = 1500;
-  let visitedDirs = 0;
-  while (queue.length > 0 && results.length < limit && visitedDirs < maxDirs) {
-    const dir = queue.shift() ?? "";
-    if (!dir)
-      continue;
-    visitedDirs += 1;
-    let entries;
-    try {
-      entries = await fs2.readdir(dir, { withFileTypes: true });
-    } catch {
-      continue;
+    context.packageJson = null;
+  }
+  return context.packageJson;
+}
+async function getPyprojectText(root, context) {
+  if (context.pyprojectLoaded)
+    return context.pyprojectText;
+  context.pyprojectLoaded = true;
+  context.pyprojectText = await readTextFileBounded(path3.join(root, "pyproject.toml"), 200000);
+  return context.pyprojectText;
+}
+async function getRequirementsText(root, context) {
+  if (context.requirementsLoaded)
+    return context.requirementsText;
+  context.requirementsLoaded = true;
+  context.requirementsText = await readTextFileBounded(path3.join(root, "requirements.txt"), 200000);
+  return context.requirementsText;
+}
+function listDependencyNames(pkg) {
+  if (!pkg)
+    return [];
+  const dependencies = pkg.dependencies ?? {};
+  const devDependencies = pkg.devDependencies ?? {};
+  const peerDependencies = pkg.peerDependencies ?? {};
+  return Object.keys({ ...dependencies, ...devDependencies, ...peerDependencies });
+}
+var HARD_SIGNATURES = [
+  {
+    profile: "pipelines_transforms",
+    reason: "Found transforms/ directory.",
+    matches: async (root) => pathExists2(path3.join(root, "transforms"))
+  },
+  {
+    profile: "pipelines_transforms",
+    reason: "Found pipelines/ directory.",
+    matches: async (root) => pathExists2(path3.join(root, "pipelines"))
+  },
+  {
+    profile: "pipelines_transforms",
+    reason: "Found internal/transforms/ directory.",
+    matches: async (root) => pathExists2(path3.join(root, "internal", "transforms"))
+  },
+  {
+    profile: "pipelines_transforms",
+    reason: "Found internal/pipeline/ directory.",
+    matches: async (root) => pathExists2(path3.join(root, "internal", "pipeline"))
+  },
+  {
+    profile: "pipelines_transforms",
+    reason: "pyproject.toml references transforms.api.",
+    matches: async (root, context) => {
+      const text = await getPyprojectText(root, context);
+      if (!text)
+        return false;
+      return /\btransforms\.api\b/i.test(text);
     }
-    for (const ent of entries) {
-      if (results.length >= limit)
-        break;
-      const full = path2.join(dir, ent.name);
-      if (ent.isDirectory()) {
-        if (ignoreDirs.has(ent.name))
-          continue;
-        queue.push(full);
-        continue;
-      }
-      if (!ent.isFile())
-        continue;
-      const ext = path2.extname(ent.name);
-      if (!allowedExts.has(ext))
-        continue;
-      results.push(full);
+  },
+  {
+    profile: "pipelines_transforms",
+    reason: "requirements.txt references transforms.api.",
+    matches: async (root, context) => {
+      const text = await getRequirementsText(root, context);
+      if (!text)
+        return false;
+      return /\btransforms\.api\b/i.test(text);
+    }
+  },
+  {
+    profile: "osdk_functions_ts",
+    reason: "package.json includes an @osdk/* dependency.",
+    matches: async (root, context) => {
+      const depNames = listDependencyNames(await getPackageJson(root, context));
+      return depNames.some((name) => name.startsWith("@osdk/"));
     }
   }
-  return results;
-}
+];
 async function scanRepoForProfile(root) {
-  const scores = {
-    pipelines_transforms: 0,
-    osdk_functions_ts: 0,
-    all: 0,
-    unknown: 0
+  const context = {
+    packageJson: null,
+    packageJsonLoaded: false,
+    pyprojectText: null,
+    pyprojectLoaded: false,
+    requirementsText: null,
+    requirementsLoaded: false
   };
-  const reasons = [];
-  const candidates = [
-    { p: "pnpm-workspace.yaml", profile: "all", score: 3, reason: "Found pnpm-workspace.yaml" },
-    { p: "turbo.json", profile: "all", score: 3, reason: "Found turbo.json" },
-    { p: "nx.json", profile: "all", score: 3, reason: "Found nx.json" },
-    { p: "lerna.json", profile: "all", score: 3, reason: "Found lerna.json" }
-  ];
-  for (const c of candidates) {
-    if (await pathExists2(path2.join(root, c.p))) {
-      addScore(scores, reasons, c.profile, c.score, c.reason);
-    }
-  }
-  const packageJsonPath = path2.join(root, "package.json");
-  const pyprojectPath = path2.join(root, "pyproject.toml");
-  const requirementsPath = path2.join(root, "requirements.txt");
-  const hasPackageJson = await pathExists2(packageJsonPath);
-  const hasPyproject = await pathExists2(pyprojectPath);
-  if (hasPackageJson && hasPyproject) {
-    addScore(scores, reasons, "all", 2, "Found both package.json and pyproject.toml");
-  }
-  if (hasPackageJson) {
-    const pkg = await parsePackageJson(packageJsonPath);
-    if (pkg) {
-      const depKeys = getAllDependencyKeys(pkg);
-      if (depKeys.some((d) => d.toLowerCase().includes("osdk") || d.startsWith("@osdk/"))) {
-        addScore(scores, reasons, "osdk_functions_ts", 5, "package.json includes OSDK dependency");
-      }
-      if (depKeys.some((d) => d.toLowerCase().includes("palantir") || d.toLowerCase().includes("foundry"))) {
-        addScore(scores, reasons, "pipelines_transforms", 1, "package.json references palantir/foundry");
-      }
-    }
-  }
-  if (hasPyproject) {
-    const text = await readTextFileBounded(pyprojectPath, 200000);
-    if (text) {
-      if (/foundry/i.test(text)) {
-        addScore(scores, reasons, "pipelines_transforms", 1, "pyproject.toml mentions foundry");
-      }
-      if (/transform/i.test(text)) {
-        addScore(scores, reasons, "pipelines_transforms", 1, "pyproject.toml mentions transform");
-      }
-    }
-  }
-  if (await pathExists2(requirementsPath)) {
-    const text = await readTextFileBounded(requirementsPath, 200000);
-    if (text) {
-      if (/foundry/i.test(text)) {
-        addScore(scores, reasons, "pipelines_transforms", 1, "requirements.txt mentions foundry");
-      }
-      if (/transform/i.test(text)) {
-        addScore(scores, reasons, "pipelines_transforms", 1, "requirements.txt mentions transform");
-      }
+  for (const signature of HARD_SIGNATURES) {
+    if (await signature.matches(root, context)) {
+      return {
+        profile: signature.profile,
+        reasons: [signature.reason]
+      };
     }
   }
-  if (await pathExists2(path2.join(root, "pipelines"))) {
-    addScore(scores, reasons, "pipelines_transforms", 3, "Found pipelines/ directory");
-  }
-  if (await pathExists2(path2.join(root, "transforms"))) {
-    addScore(scores, reasons, "pipelines_transforms", 3, "Found transforms/ directory");
-  }
-  if (await pathExists2(path2.join(root, "internal", "pipeline"))) {
-    addScore(scores, reasons, "pipelines_transforms", 3, "Found internal/pipeline/ directory");
-  }
-  if (await pathExists2(path2.join(root, "internal", "transforms"))) {
-    addScore(scores, reasons, "pipelines_transforms", 3, "Found internal/transforms/ directory");
-  }
-  if (await pathExists2(path2.join(root, "functions"))) {
-    addScore(scores, reasons, "osdk_functions_ts", 2, "Found functions/ directory");
-  }
-  if (await pathExists2(path2.join(root, "src", "functions"))) {
-    addScore(scores, reasons, "osdk_functions_ts", 2, "Found src/functions/ directory");
-  }
-  const sampleFiles = await collectSampleFiles(root, 50);
-  const maxTotalBytes = 200000;
-  let consumedBytes = 0;
-  let pipelinesHits = 0;
-  let osdkHits = 0;
-  for (const p of sampleFiles) {
-    if (consumedBytes >= maxTotalBytes)
-      break;
-    const text = await readTextFileBounded(p, 8000);
-    if (!text)
-      continue;
-    consumedBytes += text.length;
-    if (/\b(pipeline|pipelines|transform|transforms)\b/i.test(text))
-      pipelinesHits += 1;
-    if (/\bosdk\b/i.test(text))
-      osdkHits += 1;
-  }
-  if (pipelinesHits >= 3) {
-    addScore(scores, reasons, "pipelines_transforms", 2, `Keyword sample hits pipelines/transforms (${pipelinesHits})`);
-  }
-  if (osdkHits >= 2) {
-    addScore(scores, reasons, "osdk_functions_ts", 2, `Keyword sample hits osdk (${osdkHits})`);
-  }
-  const profile = pickBestProfile(scores);
-  return { profile, scores, reasons };
+  return {
+    profile: "default",
+    reasons: ["No hard signature matched. Falling back to default profile."]
+  };
 }
 
 // src/palantir-mcp/commands.ts
-function formatError3(err) {
+function formatError5(err) {
   return err instanceof Error ? err.toString() : String(err);
 }
 function isRecord2(value) {
@@ -7905,15 +8145,33 @@ function formatPatchSummary(patch) {
   return lines.join(`
 `);
 }
+function getTrimmedEnvVar(name) {
+  const raw = process.env[name];
+  if (!raw)
+    return null;
+  const trimmed = raw.trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+function formatMissingEnvGuidance(missingVars) {
+  const exports = missingVars.map((name) => `export ${name}=...`).join(`
+  `);
+  return [
+    `[ERROR] Missing required environment: ${missingVars.join(", ")}`,
+    "",
+    "Foundry MCP setup is inactive until these are exported.",
+    "Local docs tools (`get_doc_page`, `list_all_docs`) remain available.",
+    "",
+    "Set:",
+    `  ${exports}`
+  ].join(`
+`);
+}
 async function resolveProfile(worktree) {
   try {
     const scan = await scanRepoForProfile(worktree);
-    return { profile: scan.profile, reasons: scan.reasons };
+    return scan.profile;
   } catch (err) {
-    return {
-      profile: "unknown",
-      reasons: [`Repo scan failed; falling back to unknown: ${formatError3(err)}`]
-    };
+    return "default";
   }
 }
 function hasPalantirToolToggles(data, agentName) {
@@ -7937,11 +8195,11 @@ function isAutoBootstrapAlreadyComplete(data) {
 }
 async function autoBootstrapPalantirMcpIfConfigured(worktree) {
   try {
-    const tokenRaw = process.env.FOUNDRY_TOKEN;
-    const urlRaw = process.env.FOUNDRY_URL;
-    if (!tokenRaw || tokenRaw.trim().length === 0)
+    const tokenRaw = getTrimmedEnvVar("FOUNDRY_TOKEN");
+    const urlRaw = getTrimmedEnvVar("FOUNDRY_URL");
+    if (!tokenRaw)
       return;
-    if (!urlRaw || urlRaw.trim().length === 0)
+    if (!urlRaw)
       return;
     const normalized = normalizeFoundryBaseUrl(urlRaw);
     if ("error" in normalized)
@@ -7959,7 +8217,7 @@ async function autoBootstrapPalantirMcpIfConfigured(worktree) {
       return;
     const existingMcpUrlRaw = extractFoundryApiUrlFromMcpConfig(merged);
     const existingMcpUrlNorm = existingMcpUrlRaw ? normalizeFoundryBaseUrl(existingMcpUrlRaw) : null;
-    const { profile } = await resolveProfile(worktree);
+    const profile = await resolveProfile(worktree);
     const discoveryUrl = existingMcpUrlNorm && "url" in existingMcpUrlNorm ? existingMcpUrlNorm.url : normalized.url;
     const toolNames = await listPalantirMcpTools(discoveryUrl);
     if (toolNames.length === 0)
@@ -7976,7 +8234,7 @@ async function autoBootstrapPalantirMcpIfConfigured(worktree) {
     const changed = needsMigration || stableJsonStringify(merged) !== stableJsonStringify(patch.data);
     if (!changed)
       return;
-    const outPath = path3.join(worktree, OPENCODE_JSONC_FILENAME);
+    const outPath = path4.join(worktree, OPENCODE_JSONC_FILENAME);
     const text = stringifyJsonc(patch.data);
     await writeFileAtomic(outPath, text);
     if (readLegacy.ok) {
@@ -7988,18 +8246,21 @@ async function autoBootstrapPalantirMcpIfConfigured(worktree) {
 }
 async function setupPalantirMcp(worktree, rawArgs) {
   const urlFromArgs = rawArgs.trim();
-  const urlFromEnvRaw = process.env.FOUNDRY_URL;
-  const urlFromEnv = typeof urlFromEnvRaw === "string" ? urlFromEnvRaw.trim() : "";
-  const urlArg = urlFromArgs || urlFromEnv;
+  const urlFromEnv = getTrimmedEnvVar("FOUNDRY_URL");
+  const token = getTrimmedEnvVar("FOUNDRY_TOKEN");
+  const urlArg = urlFromArgs || urlFromEnv || "";
   if (!urlArg) {
+    const missingVars = ["FOUNDRY_URL"];
+    if (!token)
+      missingVars.push("FOUNDRY_TOKEN");
     return [
-      "[ERROR] Missing Foundry base URL.",
+      formatMissingEnvGuidance(missingVars),
       "",
       "Usage:",
       "  /setup-palantir-mcp <foundry_api_url>",
       "",
-      "Or set:",
-      "  export FOUNDRY_URL=<foundry_api_url>",
+      "Or pass URL directly:",
+      "  /setup-palantir-mcp https://YOUR-STACK.palantirfoundry.com",
       "",
       "Example:",
       "  /setup-palantir-mcp https://23dimethyl.usw-3.palantirfoundry.com"
@@ -8009,17 +8270,8 @@ async function setupPalantirMcp(worktree, rawArgs) {
   const normalized = normalizeFoundryBaseUrl(urlArg);
   if ("error" in normalized)
     return `[ERROR] ${normalized.error}`;
-  if (!process.env.FOUNDRY_TOKEN) {
-    return [
-      "[ERROR] FOUNDRY_TOKEN is not set in your environment.",
-      "",
-      "palantir-mcp tool discovery requires a token. Export FOUNDRY_TOKEN and retry.",
-      "",
-      "Tip: if `echo $FOUNDRY_TOKEN` prints a value but this still errors, it is likely " + "not exported.",
-      "Run `export FOUNDRY_TOKEN` (or set `export FOUNDRY_TOKEN=...` in your shell " + "secrets) and retry."
-    ].join(`
-`);
-  }
+  if (!token)
+    return formatMissingEnvGuidance(["FOUNDRY_TOKEN"]);
   const readJsonc = await readOpencodeJsonc(worktree);
   if (!readJsonc.ok && "error" in readJsonc)
     return readJsonc.error;
@@ -8031,13 +8283,13 @@ async function setupPalantirMcp(worktree, rawArgs) {
   const merged = readLegacy.ok ? mergeLegacyIntoJsonc(readLegacy.data, base) : { ...base };
   const existingMcpUrlRaw = extractFoundryApiUrlFromMcpConfig(merged);
   const existingMcpUrlNorm = existingMcpUrlRaw ? normalizeFoundryBaseUrl(existingMcpUrlRaw) : null;
-  const { profile } = await resolveProfile(worktree);
+  const profile = await resolveProfile(worktree);
   const discoveryUrl = existingMcpUrlNorm && "url" in existingMcpUrlNorm ? existingMcpUrlNorm.url : normalized.url;
   let toolNames;
   try {
     toolNames = await listPalantirMcpTools(discoveryUrl);
   } catch (err) {
-    return `[ERROR] ${formatError3(err)}`;
+    return `[ERROR] ${formatError5(err)}`;
   }
   if (toolNames.length === 0)
     return "[ERROR] palantir-mcp tool discovery returned no tools.";
@@ -8048,12 +8300,12 @@ async function setupPalantirMcp(worktree, rawArgs) {
     profile,
     allowlist
   });
-  const outPath = path3.join(worktree, OPENCODE_JSONC_FILENAME);
+  const outPath = path4.join(worktree, OPENCODE_JSONC_FILENAME);
   const text = stringifyJsonc(patch.data);
   try {
     await writeFileAtomic(outPath, text);
   } catch (err) {
-    return `[ERROR] Failed writing ${OPENCODE_JSONC_FILENAME}: ${formatError3(err)}`;
+    return `[ERROR] Failed writing ${OPENCODE_JSONC_FILENAME}: ${formatError5(err)}`;
   }
   let bakInfo = "";
   if (readLegacy.ok) {
@@ -8064,7 +8316,7 @@ async function setupPalantirMcp(worktree, rawArgs) {
 Migrated legacy ${readLegacy.path} -> ${bakPath}`;
     } catch (err) {
       bakInfo = `
-[ERROR] Wrote ${OPENCODE_JSONC_FILENAME}, but failed to rename legacy ${readLegacy.path}: ${formatError3(err)}`;
+[ERROR] Wrote ${OPENCODE_JSONC_FILENAME}, but failed to rename legacy ${readLegacy.path}: ${formatError5(err)}`;
     }
   }
   const warnings = [...normalized.warnings, ...patch.warnings];
@@ -8081,17 +8333,8 @@ Migrated legacy ${readLegacy.path} -> ${bakPath}`;
 `);
 }
 async function rescanPalantirMcpTools(worktree) {
-  if (!process.env.FOUNDRY_TOKEN) {
-    return [
-      "[ERROR] FOUNDRY_TOKEN is not set in your environment.",
-      "",
-      "palantir-mcp tool discovery requires a token. Export FOUNDRY_TOKEN and retry.",
-      "",
-      "Tip: if `echo $FOUNDRY_TOKEN` prints a value but this still errors, it is likely " + "not exported.",
-      "Run `export FOUNDRY_TOKEN` (or set `export FOUNDRY_TOKEN=...` in your shell " + "secrets) and retry."
-    ].join(`
-`);
-  }
+  if (!getTrimmedEnvVar("FOUNDRY_TOKEN"))
+    return formatMissingEnvGuidance(["FOUNDRY_TOKEN"]);
   const readJsonc = await readOpencodeJsonc(worktree);
   if (!readJsonc.ok) {
     if ("missing" in readJsonc) {
@@ -8113,23 +8356,23 @@ async function rescanPalantirMcpTools(worktree) {
   const normalized = normalizeFoundryBaseUrl(foundryUrlRaw);
   if ("error" in normalized)
     return `[ERROR] Invalid Foundry URL in config: ${normalized.error}`;
-  const { profile } = await resolveProfile(worktree);
+  const profile = await resolveProfile(worktree);
   let toolNames;
   try {
     toolNames = await listPalantirMcpTools(normalized.url);
   } catch (err) {
-    return `[ERROR] ${formatError3(err)}`;
+    return `[ERROR] ${formatError5(err)}`;
   }
   if (toolNames.length === 0)
     return "[ERROR] palantir-mcp tool discovery returned no tools.";
   const allowlist = computeAllowedTools(profile, toolNames);
   const patch = patchConfigForRescan(baseData, { toolNames, profile, allowlist });
-  const outPath = path3.join(worktree, OPENCODE_JSONC_FILENAME);
+  const outPath = path4.join(worktree, OPENCODE_JSONC_FILENAME);
   const text = stringifyJsonc(patch.data);
   try {
     await writeFileAtomic(outPath, text);
   } catch (err) {
-    return `[ERROR] Failed writing ${OPENCODE_JSONC_FILENAME}: ${formatError3(err)}`;
+    return `[ERROR] Failed writing ${OPENCODE_JSONC_FILENAME}: ${formatError5(err)}`;
   }
   const warnings = [...normalized.warnings, ...patch.warnings];
   return [
@@ -8142,37 +8385,77 @@ async function rescanPalantirMcpTools(worktree) {
 }
 
 // src/index.ts
-var NO_DB_MESSAGE = "Documentation database not found. Run /refresh-docs to download Palantir Foundry documentation.";
 var plugin = async (input) => {
-  const dbPath = path4.join(input.worktree, "data", "docs.parquet");
+  const dbPath = path5.join(input.worktree, "data", "docs.parquet");
   let dbInstance = null;
-  let autoBootstrapStarted = false;
+  let dbInitPromise = null;
+  let autoBootstrapMcpStarted = false;
+  let autoBootstrapDocsStarted = false;
+  function formatError6(err) {
+    return err instanceof Error ? err.toString() : String(err);
+  }
+  function formatBytes(bytes) {
+    if (!Number.isFinite(bytes) || bytes < 0)
+      return "0 B";
+    const units = ["B", "KB", "MB", "GB"];
+    let value = bytes;
+    let index = 0;
+    while (value >= 1024 && index < units.length - 1) {
+      value /= 1024;
+      index += 1;
+    }
+    const decimals = value >= 10 || index === 0 ? 0 : 1;
+    return `${value.toFixed(decimals)} ${units[index]}`;
+  }
+  function getMissingFoundryEnvVars() {
+    const missing = [];
+    const url = process.env.FOUNDRY_URL;
+    const token = process.env.FOUNDRY_TOKEN;
+    if (!url || url.trim().length === 0)
+      missing.push("FOUNDRY_URL");
+    if (!token || token.trim().length === 0)
+      missing.push("FOUNDRY_TOKEN");
+    return missing;
+  }
   function ensureCommandDefinitions(cfg) {
     if (!cfg.command)
       cfg.command = {};
+    const missingEnvVars = getMissingFoundryEnvVars();
+    const hasMissingToken = missingEnvVars.includes("FOUNDRY_TOKEN");
+    const setupEnvSuffix = missingEnvVars.length === 0 ? "" : ` Missing env: ${missingEnvVars.join(", ")}. Local docs tools remain available.`;
+    const rescanEnvSuffix = hasMissingToken ? " Missing env: FOUNDRY_TOKEN. Local docs tools remain available." : "";
     if (!cfg.command["refresh-docs"]) {
       cfg.command["refresh-docs"] = {
-        template: "Refresh Palantir documentation database.",
-        description: "Download Palantir docs and write data/docs.parquet (local)."
+        template: "Refresh Palantir docs snapshot (recommended).",
+        description: "Force refresh data/docs.parquet from a prebuilt snapshot (download/copy; no rescrape)."
+      };
+    }
+    if (!cfg.command["refresh-docs-rescrape"]) {
+      cfg.command["refresh-docs-rescrape"] = {
+        template: "Refresh docs by live rescrape (unsafe/experimental).",
+        description: "Explicit fallback: rescrape palantir.com docs and rebuild data/docs.parquet. Slower and less reliable than /refresh-docs."
       };
     }
     if (!cfg.command["setup-palantir-mcp"]) {
       cfg.command["setup-palantir-mcp"] = {
         template: "Set up palantir-mcp for this repo.",
-        description: "Guided MCP setup for Foundry. Usage: /setup-palantir-mcp <foundry_api_url>. Requires FOUNDRY_TOKEN for tool discovery."
+        description: `Guided MCP setup for Foundry. Usage: /setup-palantir-mcp <foundry_api_url>. Requires FOUNDRY_TOKEN for tool discovery.${setupEnvSuffix}`
       };
     }
     if (!cfg.command["rescan-palantir-mcp-tools"]) {
       cfg.command["rescan-palantir-mcp-tools"] = {
         template: "Re-scan palantir-mcp tools and patch tool gating.",
-        description: "Re-discovers the palantir-mcp tool list and adds missing palantir-mcp_* toggles (does not overwrite existing toggles). Requires FOUNDRY_TOKEN."
+        description: `Re-discovers the palantir-mcp tool list and adds missing palantir-mcp_* toggles (does not overwrite existing toggles). Requires FOUNDRY_TOKEN.${rescanEnvSuffix}`
       };
     }
   }
   function ensureAgentDefaults2(agent, agentName) {
-    const defaultDescription = agentName === "foundry-librarian" ? "Foundry exploration and context gathering (parallel-friendly)" : "Foundry execution agent (uses only enabled palantir-mcp tools)";
+    const missingEnvVars = getMissingFoundryEnvVars();
+    const envSuffix = missingEnvVars.length === 0 ? "" : ` (inactive until ${missingEnvVars.join(" and ")} ${missingEnvVars.length === 1 ? "is" : "are"} exported)`;
+    const defaultDescription = agentName === "foundry-librarian" ? `Foundry exploration and context gathering (parallel-friendly)${envSuffix}` : `Foundry execution agent (uses only enabled palantir-mcp tools)${envSuffix}`;
+    const defaultMode = agentName === "foundry" ? "all" : "subagent";
     if (agent.mode !== "subagent" && agent.mode !== "primary" && agent.mode !== "all") {
-      agent.mode = "subagent";
+      agent.mode = defaultMode;
     }
     if (typeof agent["hidden"] !== "boolean")
       agent["hidden"] = false;
@@ -8220,8 +8503,8 @@ var plugin = async (input) => {
     ensureAgentDefaults2(foundry, "foundry");
     cfg.agent.foundry = foundry;
   }
-  function maybeStartAutoBootstrap() {
-    if (autoBootstrapStarted)
+  function maybeStartAutoBootstrapMcp() {
+    if (autoBootstrapMcpStarted)
       return;
     const token = process.env.FOUNDRY_TOKEN;
     const url = process.env.FOUNDRY_URL;
@@ -8229,21 +8512,106 @@ var plugin = async (input) => {
       return;
     if (!url || url.trim().length === 0)
       return;
-    autoBootstrapStarted = true;
+    autoBootstrapMcpStarted = true;
     autoBootstrapPalantirMcpIfConfigured(input.worktree);
   }
-  async function getDb() {
-    if (!dbInstance) {
-      dbInstance = await createDatabase(dbPath);
-    }
-    return dbInstance;
+  function maybeStartAutoBootstrapDocs() {
+    if (autoBootstrapDocsStarted)
+      return;
+    autoBootstrapDocsStarted = true;
+    ensureDocsAvailable().catch(() => {});
   }
-  async function dbExists() {
-    return Bun.file(dbPath).exists();
+  function resetDb() {
+    if (dbInstance)
+      closeDatabase(dbInstance);
+    dbInstance = null;
+    dbInitPromise = null;
+  }
+  async function getDb() {
+    if (dbInstance)
+      return dbInstance;
+    if (dbInitPromise)
+      return dbInitPromise;
+    dbInitPromise = createDatabase(dbPath).then((created) => {
+      dbInstance = created;
+      return created;
+    }).finally(() => {
+      dbInitPromise = null;
+    });
+    return dbInitPromise;
   }
   function pushText(output, text) {
     output.parts.push({ type: "text", text });
   }
+  function formatSnapshotFailure(err) {
+    return [
+      "[ERROR] Unable to obtain Palantir docs snapshot.",
+      "",
+      `Reason: ${formatError6(err)}`,
+      "",
+      "Next steps:",
+      "- Retry /refresh-docs (recommended prebuilt snapshot path).",
+      "- If snapshot download is blocked, run /refresh-docs-rescrape (unsafe/experimental)."
+    ].join(`
+`);
+  }
+  function formatSnapshotRefreshEvent(event) {
+    if (event.type === "skip-existing")
+      return `snapshot_status=already_present bytes=${event.bytes}`;
+    if (event.type === "download-start")
+      return `download_attempt url=${event.url}`;
+    if (event.type === "download-failed")
+      return `download_failed url=${event.url} error=${event.error}`;
+    if (event.type === "download-success")
+      return `download_succeeded url=${event.url} bytes=${event.bytes}`;
+    if (event.type === "copy-start")
+      return `copy_attempt source=${event.sourcePath}`;
+    if (event.type === "copy-success")
+      return `copy_succeeded source=${event.sourcePath} bytes=${event.bytes}`;
+    return null;
+  }
+  async function ensureDocsAvailable(options = {}) {
+    return ensureDocsParquet({
+      dbPath,
+      force: options.force === true,
+      pluginDirectory: input.directory,
+      onEvent: options.onEvent
+    });
+  }
+  async function ensureDocsReadyForTool() {
+    try {
+      await ensureDocsAvailable();
+      return null;
+    } catch (err) {
+      return formatSnapshotFailure(err);
+    }
+  }
+  function formatRescrapeFailure(err) {
+    return [
+      "[ERROR] /refresh-docs-rescrape failed.",
+      "",
+      `Reason: ${formatError6(err)}`,
+      "",
+      "Try /refresh-docs for the recommended prebuilt snapshot flow."
+    ].join(`
+`);
+  }
+  function formatRescrapeProgressEvent(event, progressLines, failureSamples) {
+    if (event.type === "discovered") {
+      progressLines.push(`discovered_pages=${event.totalPages}`);
+      return;
+    }
+    if (event.type === "progress") {
+      progressLines.push(`processed_pages=${event.processedPages}/${event.totalPages}`);
+      return;
+    }
+    if (event.type === "page-failed") {
+      if (failureSamples.length < 5) {
+        failureSamples.push(`url=${event.url} error=${event.error}`);
+      }
+      return;
+    }
+  }
   function toPathname(inputUrl) {
     const trimmed = inputUrl.trim();
     if (trimmed.length === 0)
@@ -8297,8 +8665,8 @@ var plugin = async (input) => {
   function isInScope(pageUrl, scope) {
     if (scope === "all")
       return true;
-    const path5 = toPathname(pageUrl);
-    return path5.startsWith(`/${scope}/`) || path5.startsWith(`/docs/${scope}/`);
+    const path6 = toPathname(pageUrl);
+    return path6.startsWith(`/${scope}/`) || path6.startsWith(`/docs/${scope}/`);
   }
   function tokenizeQuery(query) {
     const tokens = query.toLowerCase().trim().split(/[\s/._-]+/g).map((t) => t.trim()).filter((t) => t.length > 0);
@@ -8308,13 +8676,13 @@ var plugin = async (input) => {
     const q = query.toLowerCase().trim();
     if (q.length === 0)
       return 0;
-    const path5 = toPathname(page.url).toLowerCase();
+    const path6 = toPathname(page.url).toLowerCase();
     const title = page.title.toLowerCase();
-    if (path5 === q)
+    if (path6 === q)
       return 2000;
-    if (path5 === toPathname(q).toLowerCase())
+    if (path6 === toPathname(q).toLowerCase())
       return 2000;
-    if (path5.includes(q))
+    if (path6.includes(q))
       return 1200;
     if (title.includes(q))
       return 1000;
@@ -8325,10 +8693,10 @@ var plugin = async (input) => {
     for (const t of tokens) {
       if (title.includes(t))
         score += 40;
-      if (path5.includes(t))
+      if (path6.includes(t))
         score += 30;
     }
-    if (path5.startsWith(q))
+    if (path6.startsWith(q))
       score += 100;
     if (title.startsWith(q))
       score += 100;
@@ -8338,7 +8706,8 @@ var plugin = async (input) => {
     config: async (cfg) => {
       ensureCommandDefinitions(cfg);
       ensureAgentDefinitions(cfg);
-      maybeStartAutoBootstrap();
+      maybeStartAutoBootstrapMcp();
+      maybeStartAutoBootstrapDocs();
     },
     tool: {
       get_doc_page: tool({
@@ -8349,8 +8718,9 @@ var plugin = async (input) => {
           scope: tool.schema.enum(["foundry", "apollo", "gotham", "all"]).optional().describe("Scope to search within when using query or fuzzy matching (default: foundry).")
         },
         async execute(args) {
-          if (!await dbExists())
-            return NO_DB_MESSAGE;
+          const docsError = await ensureDocsReadyForTool();
+          if (docsError)
+            return docsError;
           const scope = parseScope(args.scope);
           if (!scope) {
             return [
@@ -8422,8 +8792,9 @@ ${bestPage.content}`;
           query: tool.schema.string().optional().describe("Optional query to filter/rank results by title/URL (case-insensitive).")
         },
         async execute(args) {
-          if (!await dbExists())
-            return NO_DB_MESSAGE;
+          const docsError = await ensureDocsReadyForTool();
+          if (docsError)
+            return docsError;
           const scope = parseScope(args.scope);
           if (!scope) {
             return [
@@ -8502,12 +8873,65 @@ ${bestPage.content}`;
     },
     "command.execute.before": async (hookInput, output) => {
       if (hookInput.command === "refresh-docs") {
-        const result = await fetchAllDocs(dbPath);
-        if (dbInstance) {
-          closeDatabase(dbInstance);
-          dbInstance = null;
+        const progressLines = [];
+        try {
+          const result = await ensureDocsAvailable({
+            force: true,
+            onEvent: (event) => {
+              const line = formatSnapshotRefreshEvent(event);
+              if (line)
+                progressLines.push(line);
+            }
+          });
+          resetDb();
+          const db = await getDb();
+          const indexedPages = getAllPages(db).length;
+          pushText(output, [
+            "refresh-docs complete (recommended snapshot path).",
+            "",
+            ...progressLines.map((line) => `- ${line}`),
+            ...progressLines.length > 0 ? [""] : [],
+            `snapshot_source=${result.source}`,
+            result.downloadUrl ? `snapshot_url=${result.downloadUrl}` : null,
+            `snapshot_bytes=${result.bytes} (${formatBytes(result.bytes)})`,
+            `indexed_pages=${indexedPages}`
+          ].filter((line) => !!line).join(`
+`));
+        } catch (err) {
+          pushText(output, formatSnapshotFailure(err));
+        }
+        return;
+      }
+      if (hookInput.command === "refresh-docs-rescrape") {
+        const progressLines = [];
+        const failureSamples = [];
+        try {
+          const result = await fetchAllDocs(dbPath, {
+            progressEvery: 250,
+            onProgress: (event) => {
+              formatRescrapeProgressEvent(event, progressLines, failureSamples);
+            }
+          });
+          resetDb();
+          const db = await getDb();
+          const indexedPages = getAllPages(db).length;
+          pushText(output, [
+            "refresh-docs-rescrape complete (unsafe/experimental).",
+            "",
+            "Warning: this command live-scrapes palantir.com and is slower/less reliable than /refresh-docs.",
+            "",
+            ...progressLines.map((line) => `- ${line}`),
+            ...progressLines.length > 0 ? [""] : [],
+            `total_pages=${result.totalPages}`,
+            `fetched_pages=${result.fetchedPages}`,
+            `failed_pages=${result.failedUrls.length}`,
+            `indexed_pages=${indexedPages}`,
+            ...failureSamples.length > 0 ? ["", "failure_samples:", ...failureSamples.map((line) => `- ${line}`)] : []
+          ].join(`
+`));
+        } catch (err) {
+          pushText(output, formatRescrapeFailure(err));
         }
-        pushText(output, `Refreshed documentation: ${result.fetchedPages}/${result.totalPages} pages fetched. ${result.failedUrls.length} failures.`);
         return;
       }
       if (hookInput.command === "setup-palantir-mcp") {