knolo-core 0.3.0 → 3.1.0

package/DOCS.md

@@ -71,8 +71,16 @@ npx knolo docs.json knowledge.knolo
 
 # semantic-enabled build (embeddings JSON + model id)
 npx knolo docs.json knowledge.knolo --embeddings embeddings.json --model-id text-embedding-3-small
+
+# embed agents from a local directory (.json/.yml/.yaml)
+npx knolo docs.json knowledge.knolo --agents ./examples/agents
 ```
 
+
+### Agents and namespace binding
+
+When agent definitions are embedded into `meta.agents`, `resolveAgent(pack, { agentId, query, patch })` enforces **strict namespace binding**: `retrievalDefaults.namespace` always wins over caller `query.namespace`. This keeps retrieval deterministic and on-policy for each agent.
+
 ---
 
 ## Concepts
@@ -176,9 +184,15 @@ const hits: Hit[] = query(pack, '“react native bridge” throttling', {
 ### Semantic helper ergonomics
 
 ```ts
-import { hasSemantic, validateSemanticQueryOptions } from "knolo-core";
+import { hasSemantic, validateQueryOptions, validateSemanticQueryOptions } from "knolo-core";
 
 if (hasSemantic(pack)) {
+  validateQueryOptions({
+    topK: 10,
+    namespace: "mobile",
+    queryExpansion: { enabled: true, docs: 3, terms: 4 },
+  });
+
   validateSemanticQueryOptions({
     enabled: true,
     topN: 40,
@@ -188,7 +202,7 @@ if (hasSemantic(pack)) {
 }
 ```
 
-`validateSemanticQueryOptions(...)` throws useful errors for invalid option types/ranges (`topN`, `minLexConfidence`, blend weights, missing `Float32Array` embedding type).
+`validateQueryOptions(...)` and `validateSemanticQueryOptions(...)` throw useful errors for invalid option types/ranges (for example `topK`, `queryExpansion.docs`, `topN`, `minLexConfidence`, blend weights, and missing `Float32Array` embedding types).
 
 **What the ranker does**
 

package/README.md

@@ -59,21 +59,21 @@ npm run build
 ### 1) Build + mount + query
 
 ```ts
-import { buildPack, mountPack, query, makeContextPatch } from "knolo-core";
+import { buildPack, mountPack, query, makeContextPatch } from 'knolo-core';
 
 const docs = [
   {
-    id: "bridge-guide",
-    namespace: "mobile",
-    heading: "React Native Bridge",
-    text: "The bridge sends messages between JS and native modules. Throttling limits event frequency."
+    id: 'bridge-guide',
+    namespace: 'mobile',
+    heading: 'React Native Bridge',
+    text: 'The bridge sends messages between JS and native modules. Throttling limits event frequency.',
   },
   {
-    id: "perf-notes",
-    namespace: "mobile",
-    heading: "Debounce vs Throttle",
-    text: "Debounce waits for silence; throttle enforces a maximum trigger rate."
-  }
+    id: 'perf-notes',
+    namespace: 'mobile',
+    heading: 'Debounce vs Throttle',
+    text: 'Debounce waits for silence; throttle enforces a maximum trigger rate.',
+  },
 ];
 
 const bytes = await buildPack(docs);
@@ -81,11 +81,11 @@ const kb = await mountPack({ src: bytes });
 
 const hits = query(kb, '"react native" throttle', {
   topK: 5,
-  requirePhrases: ["maximum trigger rate"],
-  namespace: "mobile"
+  requirePhrases: ['maximum trigger rate'],
+  namespace: 'mobile',
 });
 
-const patch = makeContextPatch(hits, { budget: "small" });
+const patch = makeContextPatch(hits, { budget: 'small' });
 console.log(hits, patch);
 ```
 
@@ -95,22 +95,33 @@ console.log(hits, patch);
 
 ```json
 [
-  { "id": "guide", "heading": "Guide", "text": "Install deps.\n\n## Throttle\nLimit event frequency." },
-  { "id": "faq", "heading": "FAQ", "text": "What is throttling? It reduces event frequency." }
+  {
+    "id": "guide",
+    "heading": "Guide",
+    "text": "Install deps.\n\n## Throttle\nLimit event frequency."
+  },
+  {
+    "id": "faq",
+    "heading": "FAQ",
+    "text": "What is throttling? It reduces event frequency."
+  }
 ]
 ```
 
 ```bash
 npx knolo docs.json knowledge.knolo
+
+# embed agents from a local directory (.json/.yml/.yaml)
+npx knolo docs.json knowledge.knolo --agents ./examples/agents
 ```
 
 Then query in app:
 
 ```ts
-import { mountPack, query } from "knolo-core";
+import { mountPack, query } from 'knolo-core';
 
-const kb = await mountPack({ src: "./knowledge.knolo" });
-const hits = query(kb, "throttle events", { topK: 3 });
+const kb = await mountPack({ src: './knowledge.knolo' });
+const hits = query(kb, 'throttle events', { topK: 3 });
 ```
 
 ---
@@ -122,7 +133,7 @@ KnoLo’s core retrieval remains lexical-first and deterministic. Semantic signa
 ### Build a semantic-enabled pack
 
 ```ts
-import { buildPack } from "knolo-core";
+import { buildPack } from 'knolo-core';
 
 // embeddings must align 1:1 with docs/block order
 const embeddings: Float32Array[] = await embedDocumentsInOrder(docs);
@@ -130,32 +141,32 @@ const embeddings: Float32Array[] = await embedDocumentsInOrder(docs);
 const bytes = await buildPack(docs, {
   semantic: {
     enabled: true,
-    modelId: "text-embedding-3-small",
+    modelId: 'text-embedding-3-small',
     embeddings,
-    quantization: { type: "int8_l2norm", perVectorScale: true }
-  }
+    quantization: { type: 'int8_l2norm', perVectorScale: true },
+  },
 });
 ```
 
 ### Query with semantic rerank
 
 ```ts
-import { mountPack, query, hasSemantic } from "knolo-core";
+import { mountPack, query, hasSemantic } from 'knolo-core';
 
 const kb = await mountPack({ src: bytes });
-const queryEmbedding = await embedQuery("react native bridge throttling");
+const queryEmbedding = await embedQuery('react native bridge throttling');
 
-const hits = query(kb, "react native bridge throttling", {
+const hits = query(kb, 'react native bridge throttling', {
   topK: 8,
   semantic: {
     enabled: hasSemantic(kb),
-    mode: "rerank",
+    mode: 'rerank',
     topN: 50,
     minLexConfidence: 0.35,
     blend: { enabled: true, wLex: 0.75, wSem: 0.25 },
     queryEmbedding,
-    force: false
-  }
+    force: false,
+  },
 });
 ```
 
@@ -165,8 +176,8 @@ const hits = query(kb, "react native bridge throttling", {
 import {
   quantizeEmbeddingInt8L2Norm,
   encodeScaleF16,
-  decodeScaleF16
-} from "knolo-core";
+  decodeScaleF16,
+} from 'knolo-core';
 
 const { q, scale } = quantizeEmbeddingInt8L2Norm(queryEmbedding);
 const packed = encodeScaleF16(scale);
@@ -188,25 +199,75 @@ type BuildInputDoc = {
 };
 
 type BuildPackOptions = {
+  agents?: AgentRegistry | AgentDefinitionV1[];
   semantic?: {
     enabled: boolean;
     modelId: string;
     embeddings: Float32Array[];
     quantization?: {
-      type: "int8_l2norm";
+      type: 'int8_l2norm';
       perVectorScale?: true;
     };
   };
 };
 ```
 
+### Agents in pack metadata
+
+Agents are optional and embedded in `meta.agents` so a single `.knolo` artifact can ship retrieval behavior + prompt defaults on-prem. Agent registries are validated once at `mountPack()` time, so invalid embedded registries fail fast during mount.
+
+Agent namespace binding is **strict**: when `resolveAgent()` composes retrieval options, `retrievalDefaults.namespace` is always enforced and caller-provided `query.namespace` is ignored.
+
+```ts
+type AgentPromptTemplate = string[] | { format: 'markdown'; template: string };
+
+
+type AgentRegistry = {
+  version: 1;
+  agents: AgentDefinitionV1[];
+};
+
+type PackMeta = {
+  version: number;
+  stats: { docs: number; blocks: number; terms: number; avgBlockLen?: number };
+  agents?: AgentRegistry;
+};
+
+type AgentDefinitionV1 = {
+  id: string;
+  version: 1;
+  name?: string;
+  description?: string;
+  systemPrompt: AgentPromptTemplate;
+  retrievalDefaults: {
+    namespace: string[]; // required
+    topK?: number;
+    queryExpansion?: QueryOptions['queryExpansion'];
+    semantic?: Omit<
+      NonNullable<QueryOptions['semantic']>,
+      'queryEmbedding' | 'enabled' | 'force'
+    > & { enabled?: boolean };
+    minScore?: number;
+    requirePhrases?: string[];
+    source?: string[];
+  };
+  toolPolicy?: { mode: 'allow' | 'deny'; tools: string[] };
+  metadata?: Record<string, string | number | boolean | null>;
+};
+```
+
 ### `mountPack({ src }) => Promise<Pack>`
 
 ```ts
 type Pack = {
   meta: {
     version: number;
-    stats: { docs: number; blocks: number; terms: number; avgBlockLen?: number };
+    stats: {
+      docs: number;
+      blocks: number;
+      terms: number;
+      avgBlockLen?: number;
+    };
   };
   lexicon: Map<string, number>;
   postings: Uint32Array;
@@ -219,7 +280,7 @@ type Pack = {
     version: 1;
     modelId: string;
     dims: number;
-    encoding: "int8_l2norm";
+    encoding: 'int8_l2norm';
     perVectorScale: boolean;
     vecs: Int8Array;
     scales?: Uint16Array;
@@ -245,7 +306,7 @@ type QueryOptions = {
   };
   semantic?: {
     enabled?: boolean;
-    mode?: "rerank";
+    mode?: 'rerank';
     topN?: number;
     minLexConfidence?: number;
     blend?: {
@@ -267,6 +328,59 @@ type Hit = {
 };
 ```
 
+### Agent runtime helpers
+
+- `listAgents(pack) => string[]`
+- `getAgent(pack, agentId) => AgentDefinitionV1 | undefined`
+- `resolveAgent(pack, { agentId, query?, patch? }) => { agent, systemPrompt, retrievalOptions }`
+- `buildSystemPrompt(agent, patch?) => string`
+- `isToolAllowed(agent, toolId) => boolean` (defaults to allow-all when no `toolPolicy`)
+- `assertToolAllowed(agent, toolId) => void` (throws deterministic error when blocked)
+
+### Build a pack with agents and resolve at runtime
+
+```ts
+import {
+  buildPack,
+  mountPack,
+  resolveAgent,
+  query,
+  isToolAllowed,
+  assertToolAllowed,
+} from 'knolo-core';
+
+const bytes = await buildPack(docs, {
+  agents: [
+    {
+      id: 'mobile.agent',
+      version: 1,
+      systemPrompt: {
+        format: 'markdown',
+        template: 'You are {{team}} support.',
+      },
+      retrievalDefaults: { namespace: ['mobile'], topK: 5 },
+      toolPolicy: { mode: 'allow', tools: ['search_docs'] },
+    },
+  ],
+});
+
+const pack = await mountPack({ src: bytes });
+const resolved = resolveAgent(pack, {
+  agentId: 'mobile.agent',
+  patch: { team: 'mobile' },
+  query: { namespace: ['backend'], topK: 8 },
+});
+
+console.log(resolved.retrievalOptions.namespace); // ['mobile'] (strict binding)
+
+if (isToolAllowed(resolved.agent, 'search_docs')) {
+  // invoke search_docs
+}
+assertToolAllowed(resolved.agent, 'search_docs');
+
+const hits = query(pack, 'bridge throttle', resolved.retrievalOptions);
+```
+
 ### `makeContextPatch(hits, { budget }) => ContextPatch`
 
 Budgets: `"mini" | "small" | "full"`
@@ -278,10 +392,10 @@ Budgets: `"mini" | "small" | "full"`
 ### Namespace + source filtering
 
 ```ts
-const hits = query(kb, "retry backoff", {
-  namespace: ["sdk", "api"],
-  source: ["errors-guide", "http-reference"],
-  topK: 6
+const hits = query(kb, 'retry backoff', {
+  namespace: ['sdk', 'api'],
+  source: ['errors-guide', 'http-reference'],
+  topK: 6,
 });
 ```
 
@@ -290,29 +404,29 @@ const hits = query(kb, "retry backoff", {
 If your query has no free tokens but includes required phrases, KnoLo still forms candidates from phrase tokens and enforces phrase presence.
 
 ```ts
-const hits = query(kb, '"event loop"', { requirePhrases: ["single thread"] });
+const hits = query(kb, '"event loop"', { requirePhrases: ['single thread'] });
 ```
 
 ### Precision mode with minimum score
 
 ```ts
-const strictHits = query(kb, "jwt refresh token rotation", {
+const strictHits = query(kb, 'jwt refresh token rotation', {
   topK: 5,
-  minScore: 2.5
+  minScore: 2.5,
 });
 ```
 
 ### Validate semantic query options early
 
 ```ts
-import { validateSemanticQueryOptions } from "knolo-core";
+import { validateSemanticQueryOptions } from 'knolo-core';
 
 validateSemanticQueryOptions({
   enabled: true,
   topN: 40,
   minLexConfidence: 0.3,
   blend: { enabled: true, wLex: 0.8, wSem: 0.2 },
-  queryEmbedding
+  queryEmbedding,
 });
 ```
 

package/bin/knolo.mjs

@@ -1,14 +1,111 @@
 #!/usr/bin/env node
 // Robust CLI that works with ESM or CJS builds and odd resolution cases.
 
-import { readFileSync, writeFileSync } from "node:fs";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { createRequire } from "node:module";
+import { readFileSync, writeFileSync, readdirSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { createRequire } from 'node:module';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const require = createRequire(import.meta.url);
 
+function parseScalar(value) {
+  if (value === 'true') return true;
+  if (value === 'false') return false;
+  if (value === 'null') return null;
+  if (/^-?\d+(?:\.\d+)?$/.test(value)) return Number(value);
+  const quoted = value.match(/^("|')(.*)\1$/);
+  if (quoted) return quoted[2];
+  return value;
+}
+
+function parseSimpleYaml(content) {
+  const lines = content
+    .split(/\n/)
+    .map((line) => line.replace(/\r$/, ''))
+    .map((line) => line.replace(/\t/g, '  ').replace(/\s+#.*$/, ''));
+
+  const root = {};
+  const stack = [{ indent: -1, value: root }];
+
+  const nextMeaningfulLine = (from) => {
+    for (let i = from + 1; i < lines.length; i++) {
+      if (lines[i].trim()) return lines[i].trim();
+    }
+    return '';
+  };
+
+  for (let i = 0; i < lines.length; i++) {
+    const raw = lines[i];
+    if (!raw.trim()) continue;
+
+    const indent = raw.match(/^\s*/)[0].length;
+    const line = raw.trim();
+
+    while (stack.length > 1 && indent <= stack[stack.length - 1].indent) {
+      stack.pop();
+    }
+
+    const parent = stack[stack.length - 1].value;
+
+    if (line.startsWith('- ')) {
+      if (!Array.isArray(parent)) {
+        throw new Error('YAML array item found under non-array parent.');
+      }
+
+      const body = line.slice(2).trim();
+      const pair = body.match(/^([^:]+):(.*)$/);
+      if (!pair) {
+        parent.push(parseScalar(body));
+        continue;
+      }
+
+      const obj = {};
+      const key = pair[1].trim();
+      const rhs = pair[2].trim();
+      if (rhs) {
+        obj[key] = parseScalar(rhs);
+      } else {
+        const next = nextMeaningfulLine(i);
+        obj[key] = next.startsWith('- ') ? [] : {};
+        stack.push({ indent, value: obj[key] });
+      }
+      parent.push(obj);
+      continue;
+    }
+
+    const pair = line.match(/^([^:]+):(.*)$/);
+    if (!pair) {
+      throw new Error(`Unsupported YAML line: ${line}`);
+    }
+
+    const key = pair[1].trim();
+    const rhs = pair[2].trim();
+    if (Array.isArray(parent)) {
+      const obj = {};
+      parent.push(obj);
+      if (rhs) {
+        obj[key] = parseScalar(rhs);
+      } else {
+        const next = nextMeaningfulLine(i);
+        obj[key] = next.startsWith('- ') ? [] : {};
+        stack.push({ indent, value: obj[key] });
+      }
+      continue;
+    }
+
+    if (rhs) {
+      parent[key] = parseScalar(rhs);
+    } else {
+      const next = nextMeaningfulLine(i);
+      parent[key] = next.startsWith('- ') ? [] : {};
+      stack.push({ indent, value: parent[key] });
+    }
+  }
+
+  return root;
+}
+
 async function tryImport(filePath) {
   try {
     const url = pathToFileURL(filePath).href;
@@ -20,43 +117,57 @@ async function tryImport(filePath) {
   return null;
 }
 
-function getBuildPack(mod) {
-  if (!mod) return undefined;
-  if (typeof mod.buildPack === "function") return mod.buildPack;
-  if (mod.default) {
-    if (typeof mod.default === "function") return mod.default;
-    if (typeof mod.default.buildPack === "function") return mod.default.buildPack;
-  }
-  if (typeof mod === "function") return mod;
-  if (typeof mod.buildPack === "function") return mod.buildPack;
-  return undefined;
+function pickBuildExports(mod) {
+  if (!mod) return null;
+  const root = mod.default && typeof mod.default === 'object' ? mod.default : mod;
+  const buildPack =
+    typeof mod.buildPack === 'function'
+      ? mod.buildPack
+      : typeof root.buildPack === 'function'
+        ? root.buildPack
+        : typeof root === 'function'
+          ? root
+          : undefined;
+  const validateAgentDefinition =
+    typeof mod.validateAgentDefinition === 'function'
+      ? mod.validateAgentDefinition
+      : root.validateAgentDefinition;
+  const validateAgentRegistry =
+    typeof mod.validateAgentRegistry === 'function'
+      ? mod.validateAgentRegistry
+      : root.validateAgentRegistry;
+
+  if (!buildPack) return null;
+  return { buildPack, validateAgentDefinition, validateAgentRegistry };
 }
 
-async function loadBuildPack() {
+async function loadBuildExports() {
   const candidates = [
-    path.resolve(__dirname, "../dist/index.js"),
-    path.resolve(__dirname, "../dist/builder.js"),
-    path.resolve(__dirname, "../dist/index.cjs"),
-    path.resolve(__dirname, "../dist/builder.cjs"),
+    path.resolve(__dirname, '../dist/index.js'),
+    path.resolve(__dirname, '../dist/builder.js'),
+    path.resolve(__dirname, '../dist/index.cjs'),
+    path.resolve(__dirname, '../dist/builder.cjs'),
   ];
   for (const p of candidates) {
     const mod = await tryImport(p);
-    const buildPack = getBuildPack(mod);
-    if (buildPack) return buildPack;
+    const exports = pickBuildExports(mod);
+    if (exports) return exports;
   }
-  throw new Error("Could not locate a buildPack function in dist/");
+  throw new Error('Could not locate a buildPack function in dist/');
 }
 
 function validateCliDocs(raw) {
   if (!Array.isArray(raw)) {
-    throw new Error('Input JSON must be an array of docs: [{ "text": "...", "id"?: "...", "heading"?: "..." }]');
+    throw new Error(
+      'Input JSON must be an array of docs: [{ "text": "...", "id"?: "...", "heading"?: "..." }]'
+    );
   }
   for (let i = 0; i < raw.length; i++) {
     const doc = raw[i];
-    if (!doc || typeof doc !== "object") {
+    if (!doc || typeof doc !== 'object') {
       throw new Error(`Invalid doc at index ${i}: expected an object.`);
     }
-    if (typeof doc.text !== "string" || !doc.text.trim()) {
+    if (typeof doc.text !== 'string' || !doc.text.trim()) {
       throw new Error(`Invalid doc at index ${i}: "text" must be a non-empty string.`);
     }
   }
@@ -65,23 +176,27 @@ function validateCliDocs(raw) {
 
 function parseArgs(argv) {
   const positional = [];
-  const flags = { embeddingsPath: undefined, modelId: undefined };
+  const flags = { embeddingsPath: undefined, modelId: undefined, agentsDir: undefined };
 
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
-    if (!arg.startsWith("--")) {
+    if (!arg.startsWith('--')) {
       positional.push(arg);
       continue;
     }
-    if (arg === "--embeddings") {
+    if (arg === '--embeddings') {
       flags.embeddingsPath = argv[++i];
       continue;
     }
-    if (arg === "--model-id") {
+    if (arg === '--model-id') {
       flags.modelId = argv[++i];
       continue;
     }
-    if (arg === "--help" || arg === "-h") {
+    if (arg === '--agents') {
+      flags.agentsDir = argv[++i];
+      continue;
+    }
+    if (arg === '--help' || arg === '-h') {
       flags.help = true;
       continue;
     }
@@ -90,8 +205,85 @@ function parseArgs(argv) {
   return { positional, flags };
 }
 
+function parseAgentFileContent(content, filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  if (ext === '.json') return JSON.parse(content);
+  if (ext === '.yaml' || ext === '.yml') return parseSimpleYaml(content);
+  throw new Error(`Unsupported agent file extension: ${filePath}`);
+}
+
+function normalizeAgentFromFile(parsed, filePath) {
+  if (!parsed || typeof parsed !== 'object') {
+    throw new Error(`Invalid agent definition in ${filePath}: expected object.`);
+  }
+  if ('agent' in parsed && parsed.agent && typeof parsed.agent === 'object') {
+    return parsed.agent;
+  }
+  return parsed;
+}
+
+function loadAgentsFromDir(agentsDir, validators = {}) {
+  const { validateAgentDefinition, validateAgentRegistry } = validators;
+  const dirPath = path.resolve(agentsDir);
+  let entries;
+  try {
+    entries = readdirSync(dirPath, { withFileTypes: true });
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new Error(`Unable to read agents directory ${agentsDir}: ${message}`);
+  }
+
+  const files = entries
+    .filter((entry) => entry.isFile())
+    .map((entry) => entry.name)
+    .filter((name) => ['.json', '.yaml', '.yml'].includes(path.extname(name).toLowerCase()))
+    .sort((a, b) => a.localeCompare(b));
+
+  const loaded = [];
+  for (const file of files) {
+    const fullPath = path.join(dirPath, file);
+    try {
+      const content = readFileSync(fullPath, 'utf8');
+      const parsed = parseAgentFileContent(content, fullPath);
+      const agent = normalizeAgentFromFile(parsed, fullPath);
+      if (typeof validateAgentDefinition === 'function') {
+        validateAgentDefinition(agent);
+      }
+      loaded.push({ file, agent });
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Failed to load agent file ${fullPath}: ${message}`);
+    }
+  }
+
+  const duplicateById = new Map();
+  for (const item of loaded) {
+    const key = String(item.agent?.id ?? '');
+    if (!duplicateById.has(key)) duplicateById.set(key, []);
+    duplicateById.get(key).push(item.file);
+  }
+  for (const [id, fileNames] of duplicateById.entries()) {
+    if (fileNames.length > 1) {
+      throw new Error(
+        `Duplicate agent id "${id}" found in files: ${fileNames.sort((a, b) => a.localeCompare(b)).join(', ')}`
+      );
+    }
+  }
+
+  const agents = loaded
+    .map((item) => item.agent)
+    .sort((a, b) => String(a.id).localeCompare(String(b.id)));
+  const registry = { version: 1, agents };
+
+  if (typeof validateAgentRegistry === 'function') {
+    validateAgentRegistry(registry);
+  }
+
+  return registry;
+}
+
 function loadEmbeddingsFromJson(filePath, expectedCount) {
-  const parsed = JSON.parse(readFileSync(filePath, "utf8"));
+  const parsed = JSON.parse(readFileSync(filePath, 'utf8'));
   const vectors = Array.isArray(parsed?.embeddings) ? parsed.embeddings : parsed;
   if (!Array.isArray(vectors)) {
     throw new Error('Embeddings JSON must be either an array of vectors or { "embeddings": [...] }.');
@@ -102,7 +294,7 @@ function loadEmbeddingsFromJson(filePath, expectedCount) {
 
   const first = vectors[0];
   if (!Array.isArray(first) || first.length === 0) {
-    throw new Error("Embeddings must contain non-empty numeric vectors.");
+    throw new Error('Embeddings must contain non-empty numeric vectors.');
   }
   const dims = first.length;
 
@@ -126,10 +318,12 @@ function loadEmbeddingsFromJson(filePath, expectedCount) {
 }
 
 function printUsage() {
-  console.log("Usage: knolo <input.json> [output.knolo] [--embeddings embeddings.json --model-id model-name]");
+  console.log(
+    'Usage: knolo <input.json> [output.knolo] [--agents ./agents] [--embeddings embeddings.json --model-id model-name]'
+  );
 }
 
-const buildPack = await loadBuildPack();
+const { buildPack, validateAgentDefinition, validateAgentRegistry } = await loadBuildExports();
 const { positional, flags } = parseArgs(process.argv.slice(2));
 
 if (flags.help) {
@@ -138,7 +332,7 @@ if (flags.help) {
 }
 
 const inFile = positional[0];
-const outFile = positional[1] || "knowledge.knolo";
+const outFile = positional[1] || 'knowledge.knolo';
 
 if (!inFile) {
   printUsage();
@@ -146,26 +340,43 @@ if (!inFile) {
 }
 
 try {
-  const rawText = readFileSync(inFile, "utf8");
+  const rawText = readFileSync(inFile, 'utf8');
   const parsed = JSON.parse(rawText);
   const docs = validateCliDocs(parsed);
 
-  let options;
+  const options = {};
+
   if (flags.embeddingsPath || flags.modelId) {
     if (!flags.embeddingsPath || !flags.modelId) {
-      throw new Error("Both --embeddings and --model-id are required when enabling semantic build output.");
+      throw new Error('Both --embeddings and --model-id are required when enabling semantic build output.');
     }
     const embeddings = loadEmbeddingsFromJson(flags.embeddingsPath, docs.length);
-    options = {
-      semantic: {
-        enabled: true,
-        modelId: flags.modelId,
-        embeddings,
-        quantization: { type: "int8_l2norm", perVectorScale: true },
-      },
+    options.semantic = {
+      enabled: true,
+      modelId: flags.modelId,
+      embeddings,
+      quantization: { type: 'int8_l2norm', perVectorScale: true },
     };
   }
 
+  if (flags.agentsDir) {
+    let dirStats;
+    try {
+      dirStats = statSync(flags.agentsDir);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new Error(`Unable to access --agents path ${flags.agentsDir}: ${message}`);
+    }
+    if (!dirStats.isDirectory()) {
+      throw new Error(`--agents path must be a directory: ${flags.agentsDir}`);
+    }
+
+    options.agents = loadAgentsFromDir(flags.agentsDir, {
+      validateAgentDefinition,
+      validateAgentRegistry,
+    });
+  }
+
   const bytes = await buildPack(docs, options);
   writeFileSync(outFile, Buffer.from(bytes));
   console.log(`wrote ${outFile}`);

package/dist/agent.d.ts

@@ -0,0 +1,53 @@
+import type { Pack } from './pack.js';
+import type { QueryOptions } from './query.js';
+export type AgentPromptTemplate = string[] | {
+    format: 'markdown';
+    template: string;
+};
+export type AgentToolPolicy = {
+    mode: 'allow' | 'deny';
+    tools: string[];
+};
+export type AgentRetrievalDefaults = {
+    namespace: string[];
+    topK?: number;
+    queryExpansion?: QueryOptions['queryExpansion'];
+    semantic?: Omit<NonNullable<QueryOptions['semantic']>, 'queryEmbedding' | 'enabled' | 'force'> & {
+        enabled?: boolean;
+    };
+    minScore?: number;
+    requirePhrases?: string[];
+    source?: string[];
+};
+export type AgentDefinitionV1 = {
+    id: string;
+    version: 1;
+    name?: string;
+    description?: string;
+    systemPrompt: AgentPromptTemplate;
+    retrievalDefaults: AgentRetrievalDefaults;
+    toolPolicy?: AgentToolPolicy;
+    metadata?: Record<string, string | number | boolean | null>;
+};
+export type AgentRegistry = {
+    version: 1;
+    agents: AgentDefinitionV1[];
+};
+export type ResolveAgentInput = {
+    agentId: string;
+    query?: QueryOptions;
+    patch?: Record<string, string | number | boolean>;
+};
+export type ResolvedAgent = {
+    agent: AgentDefinitionV1;
+    systemPrompt: string;
+    retrievalOptions: QueryOptions;
+};
+export declare function validateAgentRegistry(reg: AgentRegistry): void;
+export declare function validateAgentDefinition(agent: AgentDefinitionV1): void;
+export declare function listAgents(pack: Pack): string[];
+export declare function getAgent(pack: Pack, agentId: string): AgentDefinitionV1 | undefined;
+export declare function buildSystemPrompt(agent: AgentDefinitionV1, patch?: Record<string, string | number | boolean>): string;
+export declare function resolveAgent(pack: Pack, input: ResolveAgentInput): ResolvedAgent;
+export declare function isToolAllowed(agent: AgentDefinitionV1, toolId: string): boolean;
+export declare function assertToolAllowed(agent: AgentDefinitionV1, toolId: string): void;

package/dist/agent.js

@@ -0,0 +1,175 @@
+import { validateQueryOptions } from './query.js';
+export function validateAgentRegistry(reg) {
+    if (!reg || typeof reg !== 'object') {
+        throw new Error('agent registry must be an object.');
+    }
+    if (reg.version !== 1) {
+        throw new Error('agent registry version must be 1.');
+    }
+    if (!Array.isArray(reg.agents)) {
+        throw new Error('agent registry agents must be an array.');
+    }
+    const seen = new Set();
+    for (const agent of reg.agents) {
+        validateAgentDefinition(agent);
+        if (seen.has(agent.id)) {
+            throw new Error(`agent id must be unique: ${agent.id}`);
+        }
+        seen.add(agent.id);
+    }
+}
+export function validateAgentDefinition(agent) {
+    if (!agent || typeof agent !== 'object') {
+        throw new Error('agent definition must be an object.');
+    }
+    if (typeof agent.id !== 'string' || !agent.id.trim()) {
+        throw new Error('agent id must be a non-empty string.');
+    }
+    if (!/^[a-z0-9]+(?:[._-][a-z0-9]+)*$/.test(agent.id)) {
+        throw new Error(`agent id must be slug-like: ${agent.id}`);
+    }
+    if (agent.version !== 1) {
+        throw new Error(`agent ${agent.id} version must be 1.`);
+    }
+    validateSystemPrompt(agent);
+    const defaults = agent.retrievalDefaults;
+    if (!defaults || typeof defaults !== 'object') {
+        throw new Error(`agent ${agent.id} retrievalDefaults must be an object.`);
+    }
+    if (!Array.isArray(defaults.namespace) ||
+        defaults.namespace.length === 0 ||
+        defaults.namespace.some((ns) => typeof ns !== 'string' || !ns.trim())) {
+        throw new Error(`agent ${agent.id} retrievalDefaults.namespace must be a non-empty string array.`);
+    }
+    if (defaults.topK !== undefined &&
+        (!Number.isInteger(defaults.topK) || defaults.topK < 1)) {
+        throw new Error(`agent ${agent.id} retrievalDefaults.topK must be a positive integer.`);
+    }
+    if (agent.toolPolicy) {
+        const { mode, tools } = agent.toolPolicy;
+        if (mode !== 'allow' && mode !== 'deny') {
+            throw new Error(`agent ${agent.id} toolPolicy.mode must be "allow" or "deny".`);
+        }
+        if (!Array.isArray(tools) ||
+            tools.some((tool) => typeof tool !== 'string' || !tool.trim())) {
+            throw new Error(`agent ${agent.id} toolPolicy.tools must be a string array.`);
+        }
+        if (new Set(tools).size !== tools.length) {
+            throw new Error(`agent ${agent.id} toolPolicy.tools must contain unique values.`);
+        }
+    }
+    const syntheticOpts = {
+        namespace: defaults.namespace,
+        topK: defaults.topK,
+        queryExpansion: defaults.queryExpansion,
+        semantic: defaults.semantic,
+        minScore: defaults.minScore,
+        requirePhrases: defaults.requirePhrases,
+        source: defaults.source,
+    };
+    validateQueryOptions(syntheticOpts);
+}
+export function listAgents(pack) {
+    const reg = pack.meta.agents;
+    if (!reg?.agents?.length)
+        return [];
+    return reg.agents.map((agent) => agent.id);
+}
+export function getAgent(pack, agentId) {
+    return pack.meta.agents?.agents.find((agent) => agent.id === agentId);
+}
+export function buildSystemPrompt(agent, patch = {}) {
+    const template = agent.systemPrompt;
+    if (Array.isArray(template)) {
+        return template.join('\n');
+    }
+    const source = template.template;
+    const placeholders = Array.from(source.matchAll(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g)).map((m) => m[1]);
+    for (const key of placeholders) {
+        if (!(key in patch)) {
+            throw new Error(`agent ${agent.id} system prompt missing patch value for placeholder: ${key}`);
+        }
+    }
+    return source.replace(/\{\{\s*([A-Za-z0-9_.-]+)\s*\}\}/g, (_match, key) => String(patch[key]));
+}
+export function resolveAgent(pack, input) {
+    const agent = getAgent(pack, input.agentId);
+    if (!agent) {
+        throw new Error(`agent not found: ${input.agentId}`);
+    }
+    const defaults = {
+        namespace: agent.retrievalDefaults.namespace,
+        topK: agent.retrievalDefaults.topK,
+        queryExpansion: agent.retrievalDefaults.queryExpansion,
+        semantic: agent.retrievalDefaults.semantic,
+        minScore: agent.retrievalDefaults.minScore,
+        requirePhrases: agent.retrievalDefaults.requirePhrases,
+        source: agent.retrievalDefaults.source,
+    };
+    const caller = input.query ?? {};
+    const retrievalOptions = {
+        ...defaults,
+        ...caller,
+        namespace: defaults.namespace,
+        queryExpansion: {
+            ...(defaults.queryExpansion ?? {}),
+            ...(caller.queryExpansion ?? {}),
+        },
+        semantic: {
+            ...(defaults.semantic ?? {}),
+            ...(caller.semantic ?? {}),
+            blend: {
+                ...(defaults.semantic?.blend ?? {}),
+                ...(caller.semantic?.blend ?? {}),
+            },
+        },
+    };
+    if (!defaults.queryExpansion && !caller.queryExpansion)
+        delete retrievalOptions.queryExpansion;
+    if (!defaults.semantic && !caller.semantic)
+        delete retrievalOptions.semantic;
+    if (retrievalOptions.semantic &&
+        !defaults.semantic?.blend &&
+        !caller.semantic?.blend) {
+        delete retrievalOptions.semantic.blend;
+    }
+    validateQueryOptions(retrievalOptions);
+    return {
+        agent,
+        systemPrompt: buildSystemPrompt(agent, input.patch),
+        retrievalOptions,
+    };
+}
+export function isToolAllowed(agent, toolId) {
+    const policy = agent.toolPolicy;
+    if (!policy)
+        return true;
+    const hasTool = policy.tools.includes(toolId);
+    if (policy.mode === 'allow') {
+        return hasTool;
+    }
+    return !hasTool;
+}
+export function assertToolAllowed(agent, toolId) {
+    if (!isToolAllowed(agent, toolId)) {
+        throw new Error(`agent ${agent.id} does not allow tool: ${toolId}`);
+    }
+}
+function validateSystemPrompt(agent) {
+    const prompt = agent.systemPrompt;
+    if (Array.isArray(prompt)) {
+        if (!prompt.length || prompt.some((line) => typeof line !== 'string')) {
+            throw new Error(`agent ${agent.id} systemPrompt must be a non-empty string array.`);
+        }
+        if (!prompt.join('').trim()) {
+            throw new Error(`agent ${agent.id} systemPrompt must not be empty.`);
+        }
+        return;
+    }
+    if (!prompt ||
+        prompt.format !== 'markdown' ||
+        typeof prompt.template !== 'string' ||
+        !prompt.template.trim()) {
+        throw new Error(`agent ${agent.id} systemPrompt markdown template must be a non-empty string.`);
+    }
+}

package/dist/builder.d.ts

@@ -1,3 +1,4 @@
+import type { AgentDefinitionV1, AgentRegistry } from './agent.js';
 export type BuildInputDoc = {
     id?: string;
     heading?: string;
@@ -5,6 +6,7 @@ export type BuildInputDoc = {
     text: string;
 };
 export type BuildPackOptions = {
+    agents?: AgentRegistry | AgentDefinitionV1[];
     semantic?: {
         enabled: boolean;
         modelId: string;

package/dist/builder.js

@@ -8,6 +8,7 @@ import { buildIndex } from './indexer.js';
 import { tokenize } from './tokenize.js';
 import { getTextEncoder } from './utils/utf8.js';
 import { encodeScaleF16, quantizeEmbeddingInt8L2Norm } from './semantic.js';
+import { validateAgentRegistry } from './agent.js';
 export async function buildPack(docs, opts = {}) {
     const normalizedDocs = validateDocs(docs);
     // Prepare blocks (strip MD) and carry heading/docId for optional boosts.
@@ -21,6 +22,7 @@ export async function buildPack(docs, opts = {}) {
     const blockTokenLens = blocks.map((b) => tokenize(b.text).length);
     const totalTokens = blockTokenLens.reduce((sum, len) => sum + len, 0);
     const avgBlockLen = blocks.length ? totalTokens / blocks.length : 1;
+    const agents = normalizeAgents(opts.agents);
     const meta = {
         version: 3,
         stats: {
@@ -29,6 +31,7 @@ export async function buildPack(docs, opts = {}) {
             terms: lexicon.length,
             avgBlockLen,
         },
+        ...(agents ? { agents } : {}),
     };
     // Persist blocks as objects to optionally carry heading/docId/token length.
     const blocksPayload = blocks.map((b, i) => ({
@@ -47,12 +50,18 @@ export async function buildPack(docs, opts = {}) {
     const semanticSection = semanticEnabled && opts.semantic
         ? buildSemanticSection(blocks.length, opts.semantic)
         : undefined;
-    const semBytes = semanticSection ? enc.encode(JSON.stringify(semanticSection.semJson)) : undefined;
+    const semBytes = semanticSection
+        ? enc.encode(JSON.stringify(semanticSection.semJson))
+        : undefined;
     const semBlob = semanticSection?.semBlob;
-    const totalLength = 4 + metaBytes.length +
-        4 + lexBytes.length +
-        4 + postings.length * 4 +
-        4 + blocksBytes.length +
+    const totalLength = 4 +
+        metaBytes.length +
+        4 +
+        lexBytes.length +
+        4 +
+        postings.length * 4 +
+        4 +
+        blocksBytes.length +
         (semanticEnabled && semBytes && semBlob
             ? 4 + semBytes.length + 4 + semBlob.length
             : 0);
@@ -92,6 +101,15 @@ export async function buildPack(docs, opts = {}) {
     }
     return out;
 }
+function normalizeAgents(input) {
+    if (!input)
+        return undefined;
+    const registry = Array.isArray(input)
+        ? { version: 1, agents: input }
+        : input;
+    validateAgentRegistry(registry);
+    return registry;
+}
 function buildSemanticSection(blockCount, semantic) {
     const { embeddings } = semantic;
     if (!Array.isArray(embeddings) || embeddings.length !== blockCount) {
@@ -133,7 +151,11 @@ function buildSemanticSection(blockCount, semantic) {
         perVectorScale: true,
         blocks: {
             vectors: { byteOffset: vecByteOffset, length: vecs.length },
-            scales: { byteOffset: scalesByteOffset, length: scales.length, encoding: 'float16' },
+            scales: {
+                byteOffset: scalesByteOffset,
+                length: scales.length,
+                encoding: 'float16',
+            },
         },
     };
     return { semJson, semBlob };

package/dist/index.d.ts

@@ -1,9 +1,11 @@
 export { mountPack, hasSemantic } from './pack.js';
-export { query, lexConfidence, validateSemanticQueryOptions } from './query.js';
+export { query, lexConfidence, validateQueryOptions, validateSemanticQueryOptions, } from './query.js';
 export { makeContextPatch } from './patch.js';
 export { buildPack } from './builder.js';
-export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16 } from './semantic.js';
+export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16, } from './semantic.js';
+export { listAgents, getAgent, resolveAgent, buildSystemPrompt, isToolAllowed, assertToolAllowed, validateAgentRegistry, validateAgentDefinition, } from './agent.js';
 export type { MountOptions, PackMeta, Pack } from './pack.js';
 export type { QueryOptions, Hit } from './query.js';
 export type { ContextPatch } from './patch.js';
 export type { BuildInputDoc, BuildPackOptions } from './builder.js';
+export type { AgentPromptTemplate, AgentToolPolicy, AgentRetrievalDefaults, AgentDefinitionV1, AgentRegistry, ResolveAgentInput, ResolvedAgent, } from './agent.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 // src/index.ts
 export { mountPack, hasSemantic } from './pack.js';
-export { query, lexConfidence, validateSemanticQueryOptions } from './query.js';
+export { query, lexConfidence, validateQueryOptions, validateSemanticQueryOptions, } from './query.js';
 export { makeContextPatch } from './patch.js';
 export { buildPack } from './builder.js';
-export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16 } from './semantic.js';
+export { quantizeEmbeddingInt8L2Norm, encodeScaleF16, decodeScaleF16, } from './semantic.js';
+export { listAgents, getAgent, resolveAgent, buildSystemPrompt, isToolAllowed, assertToolAllowed, validateAgentRegistry, validateAgentDefinition, } from './agent.js';

package/dist/pack.d.ts

@@ -1,3 +1,4 @@
+import type { AgentRegistry } from './agent.js';
 export type MountOptions = {
     src: string | ArrayBufferLike | Uint8Array;
 };
@@ -9,6 +10,7 @@ export type PackMeta = {
         terms: number;
         avgBlockLen?: number;
     };
+    agents?: AgentRegistry;
 };
 export type Pack = {
     meta: PackMeta;

package/dist/pack.js

@@ -7,6 +7,7 @@
  * Includes RN/Expo-safe TextDecoder via ponyfill.
  */
 import { getTextDecoder } from './utils/utf8.js';
+import { validateAgentRegistry } from './agent.js';
 export function hasSemantic(pack) {
     return Boolean(pack.semantic && pack.semantic.dims > 0 && pack.semantic.vecs.length > 0);
 }
@@ -21,6 +22,9 @@ export async function mountPack(opts) {
     const metaJson = dec.decode(new Uint8Array(buf, offset, metaLen));
     offset += metaLen;
     const meta = JSON.parse(metaJson);
+    if (meta.agents) {
+        validateAgentRegistry(meta.agents);
+    }
     // lexicon
     const lexLen = dv.getUint32(offset, true);
     offset += 4;
@@ -89,7 +93,17 @@ export async function mountPack(opts) {
         const semBlob = new Uint8Array(buf, offset, semBlobLen);
         semantic = parseSemanticSection(sem, semBlob);
     }
-    return { meta, lexicon, postings, blocks, headings, docIds, namespaces, blockTokenLens, semantic };
+    return {
+        meta,
+        lexicon,
+        postings,
+        blocks,
+        headings,
+        docIds,
+        namespaces,
+        blockTokenLens,
+        semantic,
+    };
 }
 function parseSemanticSection(sem, blob) {
     const vectors = sem?.blocks?.vectors;
@@ -133,12 +147,17 @@ async function resolveToBuffer(src) {
     return src;
 }
 function isNodeRuntime() {
-    return typeof process !== 'undefined' && !!process.versions?.node;
+    const p = globalThis
+        .process;
+    return !!p?.versions?.node;
 }
 function isLikelyLocalPath(value) {
     if (value.startsWith('file://'))
         return true;
-    if (value.startsWith('./') || value.startsWith('../') || value.startsWith('/') || value.startsWith('~'))
+    if (value.startsWith('./') ||
+        value.startsWith('../') ||
+        value.startsWith('/') ||
+        value.startsWith('~'))
         return true;
     if (/^[A-Za-z]:[\\/]/.test(value))
         return true; // Windows absolute path

package/dist/query.d.ts

@@ -26,6 +26,7 @@ export type QueryOptions = {
         force?: boolean;
     };
 };
+export declare function validateQueryOptions(opts?: QueryOptions): void;
 export declare function validateSemanticQueryOptions(options?: QueryOptions["semantic"]): void;
 export type Hit = {
     blockId: number;

package/dist/query.js

@@ -14,6 +14,40 @@ import { minCoverSpan, proximityMultiplier } from "./quality/proximity.js";
 import { diversifyAndDedupe } from "./quality/diversify.js";
 import { knsSignature, knsDistance } from "./quality/signature.js";
 import { decodeScaleF16, quantizeEmbeddingInt8L2Norm } from "./semantic.js";
+export function validateQueryOptions(opts) {
+    if (!opts)
+        return;
+    if (opts.topK !== undefined && (!Number.isInteger(opts.topK) || opts.topK < 1)) {
+        throw new Error("query(...): topK must be a positive integer.");
+    }
+    if (opts.minScore !== undefined && (!Number.isFinite(opts.minScore) || opts.minScore < 0)) {
+        throw new Error("query(...): minScore must be a finite number >= 0.");
+    }
+    if (opts.requirePhrases !== undefined && (!Array.isArray(opts.requirePhrases) || opts.requirePhrases.some((p) => typeof p !== "string"))) {
+        throw new Error("query(...): requirePhrases must be an array of strings when provided.");
+    }
+    validateStringOrStringArrayOption("namespace", opts.namespace);
+    validateStringOrStringArrayOption("source", opts.source);
+    if (opts.queryExpansion) {
+        const qe = opts.queryExpansion;
+        if (qe.enabled !== undefined && typeof qe.enabled !== "boolean") {
+            throw new Error("query(...): queryExpansion.enabled must be a boolean when provided.");
+        }
+        if (qe.docs !== undefined && (!Number.isInteger(qe.docs) || qe.docs < 1)) {
+            throw new Error("query(...): queryExpansion.docs must be a positive integer.");
+        }
+        if (qe.terms !== undefined && (!Number.isInteger(qe.terms) || qe.terms < 1)) {
+            throw new Error("query(...): queryExpansion.terms must be a positive integer.");
+        }
+        if (qe.weight !== undefined && (!Number.isFinite(qe.weight) || qe.weight < 0)) {
+            throw new Error("query(...): queryExpansion.weight must be a finite number >= 0.");
+        }
+        if (qe.minTermLength !== undefined && (!Number.isInteger(qe.minTermLength) || qe.minTermLength < 1)) {
+            throw new Error("query(...): queryExpansion.minTermLength must be a positive integer.");
+        }
+    }
+    validateSemanticQueryOptions(opts.semantic);
+}
 export function validateSemanticQueryOptions(options) {
     if (!options)
         return;
@@ -48,7 +82,7 @@ export function validateSemanticQueryOptions(options) {
     }
 }
 export function query(pack, q, opts = {}) {
-    validateSemanticQueryOptions(opts.semantic);
+    validateQueryOptions(opts);
     const topK = opts.topK ?? 10;
     const minScore = Number.isFinite(opts.minScore) ? Math.max(0, opts.minScore) : 0;
     const expansionOpts = {
@@ -419,3 +453,11 @@ function normalizeSourceFilter(input) {
     const values = Array.isArray(input) ? input : [input];
     return new Set(values.map((v) => normalize(v)).filter(Boolean));
 }
+function validateStringOrStringArrayOption(name, value) {
+    if (value === undefined)
+        return;
+    const valid = typeof value === "string" || (Array.isArray(value) && value.every((entry) => typeof entry === "string"));
+    if (!valid) {
+        throw new Error(`query(...): ${name} must be a string or an array of strings when provided.`);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "knolo-core",
-  "version": "0.3.0",
+  "version": "3.1.0",
   "type": "module",
   "description": "Local-first knowledge packs for small LLMs.",
   "keywords": [
@@ -34,7 +34,9 @@
     "build": "tsc -p tsconfig.json",
     "prepublishOnly": "npm run build",
     "smoke": "node scripts/smoke.mjs",
-    "test": "npm run build && node scripts/test.mjs"
+    "test": "npm run build && node scripts/test.mjs",
+    "format": "prettier --write src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs README.md",
+    "format:check": "prettier --check src/agent.ts src/pack.ts src/builder.ts src/index.ts scripts/test.mjs README.md"
   },
   "devDependencies": {
     "typescript": "^5.5.0",