@jangts/agent-core 0.1.1 → 0.2.1

package/development/skills/agent-core-app/scripts/lib/knowledge.mjs

@@ -1,38 +1,99 @@
+/**
+ * App-owned knowledge loading for the `agent-core-app` Skill.
+ *
+ * Reads the App's `knowledge.config.json` allowlist, verifies each referenced document against the
+ * configured byte limit, and compiles the documents into a Knowledge Kit catalog. This is App
+ * configuration code, not a Core file-store API: no model or request may supply a filesystem path.
+ *
+ * Exports: `compileApplicationKnowledge`, `readApplicationKnowledge`, `loadApplicationKnowledge`.
+ */
 import { readFile } from 'node:fs/promises';
 import { createHash } from 'node:crypto';
 import { Knowledge } from '@jangts/agent-core/kits/knowledge';
 
-// This is App-owned configuration and loading code, not a Core file-store API.
+/**
+ * Compile parsed documents into a Knowledge catalog.
+ *
+ * @param documents Documents produced by `Knowledge.parseKnowledgeDocument`.
+ * @param policy Validated `knowledge.config.json` content (`schemaVersion`, `maxReadChars`,
+ *   `requiredReads`).
+ * @returns The compiled catalog; required reads are resolved so a missing read fails here.
+ * @throws {TypeError} When the policy shape or a required read is invalid.
+ */
 export function compileApplicationKnowledge(documents, policy) {
-  if (!policy || policy.schemaVersion !== 1 || !Number.isSafeInteger(policy.maxReadChars) || policy.maxReadChars < 1
-    || !Array.isArray(policy.requiredReads)) throw new TypeError('Invalid application knowledge policy');
+  if (
+    !policy ||
+    policy.schemaVersion !== 1 ||
+    !Number.isSafeInteger(policy.maxReadChars) ||
+    policy.maxReadChars < 1 ||
+    !Array.isArray(policy.requiredReads)
+  )
+    throw new TypeError('Invalid application knowledge policy');
   const catalog = Knowledge.defineKnowledgeCatalog(documents, { maxChars: policy.maxReadChars });
   // Required task reads must fit their runtime content budget as well as resolve.
   for (const read of policy.requiredReads) catalog.read(read);
   return catalog;
 }
 
+/**
+ * Read the knowledge config and its allowed documents from one directory.
+ *
+ * The config hash is computed over the exact bytes parsed below, so a proposal identity cannot
+ * drift from the document catalog it was derived from.
+ *
+ * @param directory Directory holding `knowledge.config.json` and the listed documents.
+ * @returns Parsed `documents`, the raw `policy` and the `baseConfigSha256` of the config file.
+ * @throws {TypeError} When the config or a document entry fails validation.
+ * @throws {RangeError} When a source document exceeds `maxDocumentBytes`.
+ */
 export async function readApplicationKnowledge(directory = new URL('./', import.meta.url)) {
   // Bind validation and proposal identity to the exact bytes parsed below.
   const configBytes = await readFile(new URL('knowledge.config.json', directory));
   const baseConfigSha256 = createHash('sha256').update(configBytes).digest('hex');
   const policy = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(configBytes));
-  if (!Array.isArray(policy.documents) || !Number.isSafeInteger(policy.maxDocumentBytes)
-    || policy.maxDocumentBytes < 1) throw new TypeError('Invalid application document catalog');
-  const documents = await Promise.all(policy.documents.map(async entry => {
-    // The allowlist is App-maintained. Neither a model nor a request supplies this filesystem path.
-    if (!entry || typeof entry.id !== 'string' || typeof entry.file !== 'string'
-      || !/^[a-z0-9][a-z0-9.-]*\.knowledge\.md$/.test(entry.file)
-      || (entry.locale !== undefined && typeof entry.locale !== 'string')) throw new TypeError('Invalid application document entry');
-    const bytes = await readFile(new URL(entry.file, directory));
-    if (bytes.length > policy.maxDocumentBytes) throw new RangeError('Source document exceeds the App limit');
-    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
-    const revision = createHash('sha256').update(JSON.stringify([entry.id, entry.locale, text])).digest('hex');
-    return Knowledge.parseKnowledgeDocument({ id: entry.id, revision, locale: entry.locale, text });
-  }));
+  if (
+    !Array.isArray(policy.documents) ||
+    !Number.isSafeInteger(policy.maxDocumentBytes) ||
+    policy.maxDocumentBytes < 1
+  )
+    throw new TypeError('Invalid application document catalog');
+  const documents = await Promise.all(
+    policy.documents.map(async (entry) => {
+      // The allowlist is App-maintained. Neither a model nor a request supplies this filesystem path.
+      if (
+        !entry ||
+        typeof entry.id !== 'string' ||
+        typeof entry.file !== 'string' ||
+        !/^[a-z0-9][a-z0-9.-]*\.knowledge\.md$/.test(entry.file) ||
+        (entry.locale !== undefined && typeof entry.locale !== 'string')
+      )
+        throw new TypeError('Invalid application document entry');
+      const bytes = await readFile(new URL(entry.file, directory));
+      if (bytes.length > policy.maxDocumentBytes)
+        throw new RangeError('Source document exceeds the App limit');
+      const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+      const revision = createHash('sha256')
+        .update(JSON.stringify([entry.id, entry.locale, text]))
+        .digest('hex');
+      return Knowledge.parseKnowledgeDocument({
+        id: entry.id,
+        revision,
+        locale: entry.locale,
+        text,
+      });
+    }),
+  );
   return { documents, policy, baseConfigSha256 };
 }
 
+/**
+ * Read and compile the App knowledge catalog in one step.
+ *
+ * @param directory Directory holding `knowledge.config.json` and the listed documents.
+ * @returns The compiled Knowledge catalog.
+ * @throws {TypeError | RangeError} Same validation failures as `readApplicationKnowledge` and
+ *   `compileApplicationKnowledge`.
+ */
 export async function loadApplicationKnowledge(directory = new URL('./', import.meta.url)) {
   const { documents, policy } = await readApplicationKnowledge(directory);
   return compileApplicationKnowledge(documents, policy);

package/development/skills/agent-core-app/scripts/lib/source.mjs

@@ -1,16 +1,44 @@
+/*
+ * Reader for a knowledge source file supplied by the operator.
+ *
+ * The file belongs to the App's development skills (开发技能). It turns one UTF-8 source
+ * file into a parsed knowledge document plus the hashes that identify it. The Knowledge
+ * Kit owns the document contract; this module only owns the file access, the byte budget
+ * and the identity derivation.
+ *
+ * Main exports: `readSuppliedSource`.
+ */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
 import { createHash } from 'node:crypto';
 import { Knowledge } from '@jangts/agent-core/kits/knowledge';
 
+/**
+ * Read and parse one supplied knowledge source file.
+ *
+ * @param file - Path of the UTF-8 source file.
+ * @param id - Stable document id; must be a lowercase slug of at most 64 characters.
+ * @param maxBytes - Maximum accepted file size in bytes.
+ * @param locale - Optional locale carried over from the document this one replaces.
+ * @returns The raw bytes, the parsed document, the original file name and the content hash.
+ * @throws TypeError For an invalid document id or a file that is not valid UTF-8.
+ * @throws RangeError When the file is empty or exceeds the byte budget.
+ * @throws Error When the decoded text is blank, or the anchors of the document are invalid.
+ */
 export async function readSuppliedSource(file, id, maxBytes = 32000, locale) {
+  // The id becomes part of the published document identity, so its shape is fixed.
   if (!/^[a-z][a-z0-9_.:-]{0,63}$/.test(id)) throw new TypeError('Choose a stable document ID');
   const bytes = await readFile(file);
-  if (!bytes.length || bytes.length > maxBytes) throw new RangeError('Source must contain text within the configured byte budget');
+  if (!bytes.length || bytes.length > maxBytes)
+    throw new RangeError('Source must contain text within the configured byte budget');
+  // `fatal` rejects malformed UTF-8 instead of replacing the invalid bytes.
   const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
   if (!text.trim()) throw new Error('Source has no content; use empty initialization instead');
+  // The content hash covers the raw bytes; the revision covers the parsed identity.
   const digest = createHash('sha256').update(bytes).digest('hex');
-  const revision = createHash('sha256').update(JSON.stringify([id, locale, text])).digest('hex');
+  const revision = createHash('sha256')
+    .update(JSON.stringify([id, locale, text]))
+    .digest('hex');
   const document = Knowledge.parseKnowledgeDocument({ id, revision, locale, text });
   return { bytes, document, name: basename(file), digest };
 }

package/development/skills/agent-core-app/scripts/plan.mjs

@@ -1,3 +1,12 @@
+/**
+ * Read-only planning entry for the `agent-core-app` Skill.
+ *
+ * Reports whether a project exists, which SDK it resolves, the state of its knowledge catalog and
+ * the SDK tools/docs that may be used next. It never evaluates project code, calls a model or
+ * writes files; the printed JSON is guidance for the agent, not a permission grant.
+ *
+ * Usage: `node plan.mjs PROJECT [--source UTF8_FILE]`.
+ */
 import { stat } from 'node:fs/promises';
 import { resolve, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -9,28 +18,53 @@ if (![1, 3].includes(args.length) || (args.length === 3 && args[1] !== '--source
   throw new Error('Usage: node plan.mjs PROJECT [--source UTF8_FILE]');
 const project = resolve(args[0]);
 let exists = true;
-try { if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory'); }
-catch (error) { if (error.code !== 'ENOENT') throw error; exists = false; }
+try {
+  if (!(await stat(project)).isDirectory()) throw new TypeError('PROJECT must be a directory');
+} catch (error) {
+  if (error.code !== 'ENOENT') throw error;
+  exists = false;
+}
 const { sdk, tools, docs, knowledgeLoader } = await resolveSdkResources(project);
 let documents = [];
 let knowledgeConfigured = false;
 let knowledgeStatus = 'unconfigured';
 let baseConfigSha256;
 if (exists) {
-  try { await stat(resolve(project, 'knowledge.config.json')); knowledgeConfigured = true; }
-  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  try {
+    await stat(resolve(project, 'knowledge.config.json'));
+    knowledgeConfigured = true;
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
   if (knowledgeConfigured) {
-    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(pathToFileURL(knowledgeLoader));
+    const { readApplicationKnowledge, compileApplicationKnowledge } = await import(
+      pathToFileURL(knowledgeLoader)
+    );
     const snapshot = await readApplicationKnowledge(pathToFileURL(project + sep));
     const catalog = compileApplicationKnowledge(snapshot.documents, snapshot.policy);
-    documents = snapshot.policy.documents.map(item => ({ id: item.id, file: item.file }));
+    documents = snapshot.policy.documents.map((item) => ({ id: item.id, file: item.file }));
     knowledgeStatus = catalog.ids().length ? 'valid' : 'empty-awaiting-source';
     baseConfigSha256 = snapshot.baseConfigSha256;
   }
 }
-console.log(JSON.stringify({ project, mode: exists ? 'integrate-or-maintain' : 'create-application', sdk,
-  knowledgeConfigured, knowledgeStatus, baseConfigSha256, suppliedSource: args[2] ? resolve(args[2]) : null,
-  factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
-  documents, tools, docs,
-  changedFiles: [], published: false,
-}, null, 2));
+console.log(
+  JSON.stringify(
+    {
+      project,
+      mode: exists ? 'integrate-or-maintain' : 'create-application',
+      sdk,
+      knowledgeConfigured,
+      knowledgeStatus,
+      baseConfigSha256,
+      suppliedSource: args[2] ? resolve(args[2]) : null,
+      factsPolicy: 'Use only supplied source; with ideas only, keep knowledge files empty.',
+      documents,
+      tools,
+      docs,
+      changedFiles: [],
+      published: false,
+    },
+    null,
+    2,
+  ),
+);

package/development/skills/agent-core-app/scripts/prepare-source.mjs

@@ -1,3 +1,14 @@
+/*
+ * Prepare a knowledge candidate from a supplied source file.
+ *
+ * The script belongs to the App's development skills (开发技能). It never touches the
+ * active knowledge files: it validates the new document against the current catalog
+ * and writes a self-contained candidate directory that a later publication step can
+ * approve. The candidate records the base configuration hash and the revisions of the
+ * documents it was prepared against, so the publication can detect a stale base.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { mkdir, writeFile } from 'node:fs/promises';
 import { resolve, join, sep } from 'node:path';
 import { pathToFileURL } from 'node:url';
@@ -8,17 +19,57 @@ import { readApplicationKnowledge, compileApplicationKnowledge } from './lib/kno
 const args = process.argv.slice(2);
 if (args.length !== 5 || args[1] !== '--source' || args[3] !== '--id')
   throw new Error('Usage: node prepare-source.mjs PROJECT --source UTF8_FILE --id DOCUMENT_ID');
-const project = resolve(args[0]), directory = pathToFileURL(project + sep);
+const project = resolve(args[0]),
+  // A trailing separator makes the directory a base URL, so relative entries
+  // resolve inside the project instead of against the file system root.
+  directory = pathToFileURL(project + sep);
 const { documents, policy, baseConfigSha256 } = await readApplicationKnowledge(directory);
-const previous = documents.find(item => item.id === args[4]);
-const source = await readSuppliedSource(resolve(args[2]), args[4], policy.maxDocumentBytes, previous?.locale);
-compileApplicationKnowledge([...documents.filter(item => item.id !== args[4]), source.document], policy);
-const target = join(project, '.local', 'knowledge-candidates', args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID());
+// A document with the same id is replaced rather than added.
+const previous = documents.find((item) => item.id === args[4]);
+const source = await readSuppliedSource(
+  resolve(args[2]),
+  args[4],
+  policy.maxDocumentBytes,
+  // The locale of the replaced document is carried over, so the revision stays
+  // comparable across the replacement.
+  previous?.locale,
+);
+// The candidate must fit the catalog together with the other documents, so the
+// whole set is compiled before anything is written.
+compileApplicationKnowledge(
+  [...documents.filter((item) => item.id !== args[4]), source.document],
+  policy,
+);
+const target = join(
+  project,
+  '.local',
+  'knowledge-candidates',
+  // The random suffix keeps two candidates for the same document apart.
+  args[4].replace(/[^a-z0-9_.-]/g, '_') + '-' + randomUUID(),
+);
 await mkdir(target, { recursive: true });
+// `wx` fails instead of overwriting an existing file.
 await writeFile(join(target, 'source.knowledge.md'), source.bytes, { flag: 'wx' });
-await writeFile(join(target, 'proposal.json'), JSON.stringify({ schemaVersion: 1, status: 'candidate', document: args[4],
-  action: previous ? 'replace' : 'add', originalName: source.name, locale: source.document.locale,
-  contentSha256: source.digest, revision: source.document.revision, baseConfigSha256,
-  baseDocuments: documents.map(item => ({ id: item.id, revision: item.revision })), published: false,
-}, null, 2) + '\n', { flag: 'wx' });
+await writeFile(
+  join(target, 'proposal.json'),
+  JSON.stringify(
+    {
+      schemaVersion: 1,
+      status: 'candidate',
+      document: args[4],
+      action: previous ? 'replace' : 'add',
+      originalName: source.name,
+      locale: source.document.locale,
+      contentSha256: source.digest,
+      revision: source.document.revision,
+      baseConfigSha256,
+      baseDocuments: documents.map((item) => ({ id: item.id, revision: item.revision })),
+      published: false,
+    },
+    null,
+    2,
+  ) + '\n',
+  { flag: 'wx' },
+);
+// The receipt states that nothing was published and no active file was changed.
 console.log(JSON.stringify({ candidate: target, published: false, activeFilesChanged: false }));

package/development/skills/agent-core-app/scripts/resources.mjs

@@ -1,3 +1,13 @@
+/**
+ * Locate the SDK installation and the Skill assets it ships.
+ *
+ * The Skill never downloads or copies files: it resolves the `@jangts/agent-core` installation the
+ * target project already depends on, or — only when this Skill runs from inside the distributed
+ * SDK — the bundled sibling assets. Every returned path is verified to be a regular file so a
+ * broken or foreign package cannot silently supply a different asset.
+ *
+ * Exports: `resolveSdkResources`.
+ */
 import { createRequire } from 'node:module';
 import { readFile, stat } from 'node:fs/promises';
 import { dirname, join, resolve } from 'node:path';
@@ -11,12 +21,17 @@ const assets = {
     'prepare-source': 'skills/agent-core-app/scripts/prepare-source.mjs',
   },
   docs: {
-    guide: 'docs/README.md', api: 'docs/api/README.md',
-    maintenance: 'docs/maintenance.md', flow: 'docs/flows/knowledge-maintenance.md',
-    gettingStarted: 'docs/getting-started.md', knowledge: 'docs/knowledge.md',
+    guide: 'docs/README.md',
+    api: 'docs/api/README.md',
+    maintenance: 'docs/maintenance.md',
+    flow: 'docs/flows/knowledge-maintenance.md',
+    gettingStarted: 'docs/getting-started.md',
+    knowledge: 'docs/knowledge.md',
     createApp: 'docs/create-app.md',
-    materials: 'docs/materials.md', memory: 'docs/memory-and-learning.md',
-    answering: 'docs/api/knowledge-answering.md', acceptance: 'docs/acceptance.md',
+    materials: 'docs/materials.md',
+    memory: 'docs/memory-and-learning.md',
+    answering: 'docs/api/knowledge-answering.md',
+    acceptance: 'docs/acceptance.md',
   },
 };
 
@@ -24,28 +39,37 @@ async function packageAt(directory) {
   try {
     const manifest = JSON.parse(await readFile(join(directory, 'package.json'), 'utf8'));
     return manifest.name === packageName ? manifest : undefined;
-  } catch (error) { if (error.code !== 'ENOENT') throw error; }
+  } catch (error) {
+    if (error.code !== 'ENOENT') throw error;
+  }
 }
 
 async function installedPackage(project) {
   // Node resolves the public entry without loading it or evaluating App code.
   const require = createRequire(pathToFileURL(join(project, '__agent_core_resolution__.cjs')));
   let entry;
-  try { entry = require.resolve(packageName); }
-  catch (error) {
+  try {
+    entry = require.resolve(packageName);
+  } catch (error) {
     if (error.code !== 'MODULE_NOT_FOUND') throw error;
     // A broken installed entry must not silently select a different SDK version.
     for (const directory of require.resolve.paths(packageName) ?? []) {
-      try { await stat(join(directory, packageName)); }
-      catch (missing) { if (missing.code === 'ENOENT') continue; throw missing; }
+      try {
+        await stat(join(directory, packageName));
+      } catch (missing) {
+        if (missing.code === 'ENOENT') continue;
+        throw missing;
+      }
       throw error;
     }
     return;
   }
   for (let directory = dirname(entry); ; directory = dirname(directory)) {
     const manifest = await packageAt(directory);
-    if (manifest) return { root: directory, version: manifest.version, source: 'project-dependency' };
-    if (dirname(directory) === directory) throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
+    if (manifest)
+      return { root: directory, version: manifest.version, source: 'project-dependency' };
+    if (dirname(directory) === directory)
+      throw new Error(`Cannot locate ${packageName} manifest for resolved entry ${entry}`);
   }
 }
 
@@ -55,21 +79,42 @@ async function requiredFile(root, relative) {
   return filename;
 }
 
+/**
+ * Resolve the SDK root and every Skill resource path for one project.
+ *
+ * @param project Project directory used to resolve the installed SDK.
+ * @returns `sdk` (`root`, `version`, `source`), the `tools`/`docs` file paths and `knowledgeLoader`.
+ * @throws {Error} When the SDK cannot be resolved, or a declared resource is missing or not a file.
+ */
 export async function resolveSdkResources(project) {
   let sdk = await installedPackage(resolve(project));
   if (!sdk) {
     // Only the Skill distributed inside the SDK can use sibling assets.
     const root = fileURLToPath(new URL('../../../../', import.meta.url));
-    const bundled = resolve(fileURLToPath(import.meta.url)) === resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
+    const bundled =
+      resolve(fileURLToPath(import.meta.url)) ===
+      resolve(root, 'development/skills/agent-core-app/scripts/resources.mjs');
     const manifest = bundled ? await packageAt(root) : undefined;
-    if (!manifest) throw new Error(`Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`);
+    if (!manifest)
+      throw new Error(
+        `Cannot resolve ${packageName} from ${project}. Install the SDK and its real dependencies in the existing App, or use the Skill inside the distributed SDK.`,
+      );
     sdk = { root, version: manifest.version, source: 'bundled-sdk' };
   }
   const resources = {};
   for (const [group, entries] of Object.entries(assets)) {
-    resources[group] = Object.fromEntries(await Promise.all(Object.entries(entries)
-      .map(async ([name, relative]) => [name, await requiredFile(sdk.root, relative)])));
+    resources[group] = Object.fromEntries(
+      await Promise.all(
+        Object.entries(entries).map(async ([name, relative]) => [
+          name,
+          await requiredFile(sdk.root, relative),
+        ]),
+      ),
+    );
   }
-  const knowledgeLoader = await requiredFile(sdk.root, 'skills/agent-core-app/scripts/lib/knowledge.mjs');
+  const knowledgeLoader = await requiredFile(
+    sdk.root,
+    'skills/agent-core-app/scripts/lib/knowledge.mjs',
+  );
   return { sdk, ...resources, knowledgeLoader };
 }

package/development/skills/agent-core-app/scripts/validate-knowledge.mjs

@@ -1,8 +1,25 @@
+/*
+ * Validate the active knowledge catalog of one project.
+ *
+ * The script belongs to the App's development skills (开发技能). It loads the App-owned
+ * configuration and document files, compiles them into a Knowledge catalog and reports
+ * the resulting document ids. An empty catalog is reported as a distinct status, so a
+ * project that has not received its first source is not confused with a broken one.
+ *
+ * Main exports: none. The file runs as a command and prints one JSON receipt.
+ */
 import { pathToFileURL } from 'node:url';
 import { resolve, sep } from 'node:path';
 import { loadApplicationKnowledge } from './lib/knowledge.mjs';
 
 if (process.argv.length !== 3) throw new Error('Usage: node validate-knowledge.mjs PROJECT');
+// A trailing separator turns the project path into a base URL, so the document
+// entries resolve inside the project directory.
 const directory = pathToFileURL(resolve(process.argv[2]) + sep);
 const catalog = await loadApplicationKnowledge(directory);
-console.log(JSON.stringify({ status: catalog.ids().length ? 'valid' : 'empty-awaiting-source', documents: catalog.ids() }));
+console.log(
+  JSON.stringify({
+    status: catalog.ids().length ? 'valid' : 'empty-awaiting-source',
+    documents: catalog.ids(),
+  }),
+);

package/development/skills/agent-core-app/templates/catalog.json

@@ -1,25 +1,39 @@
 {
   "schemaVersion": 1,
-  "templates": [{
-    "id": "node-ts",
-    "revision": "1",
-    "directory": "node-ts",
-    "files": [
-      { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
-      { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
-      { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
-      { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
-      { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
-      { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
-      { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
-      { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
-      { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
-      { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
-      { "origin": "template", "source": "scripts/knowledge.mjs.tpl", "target": "scripts/knowledge.mjs" },
-      { "origin": "skill", "source": "scripts/resources.mjs", "target": "scripts/sdk-resources.mjs" },
-      { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
-      { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
-      { "origin": "template", "source": "knowledge/knowledge.config.json.tpl", "target": "knowledge/knowledge.config.json" }
-    ]
-  }]
+  "templates": [
+    {
+      "id": "node-ts",
+      "revision": "1",
+      "directory": "node-ts",
+      "files": [
+        { "origin": "template", "source": "package.json.tpl", "target": "package.json" },
+        { "origin": "template", "source": "tsconfig.json.tpl", "target": "tsconfig.json" },
+        { "origin": "template", "source": "gitignore.tpl", "target": ".gitignore" },
+        { "origin": "template", "source": "env.example.tpl", "target": ".env.example" },
+        { "origin": "template", "source": "README.md.tpl", "target": "README.md" },
+        { "origin": "template", "source": "src/config.ts.tpl", "target": "src/config.ts" },
+        { "origin": "template", "source": "src/app.ts.tpl", "target": "src/app.ts" },
+        { "origin": "template", "source": "src/catalog.ts.tpl", "target": "src/catalog.ts" },
+        { "origin": "template", "source": "src/handlers.ts.tpl", "target": "src/handlers.ts" },
+        { "origin": "template", "source": "src/model.ts.tpl", "target": "src/model.ts" },
+        {
+          "origin": "template",
+          "source": "scripts/knowledge.mjs.tpl",
+          "target": "scripts/knowledge.mjs"
+        },
+        {
+          "origin": "skill",
+          "source": "scripts/resources.mjs",
+          "target": "scripts/sdk-resources.mjs"
+        },
+        { "origin": "template", "source": "examples/ask.mjs.tpl", "target": "examples/ask.mjs" },
+        { "origin": "template", "source": "test/app.test.mjs.tpl", "target": "test/app.test.mjs" },
+        {
+          "origin": "template",
+          "source": "knowledge/knowledge.config.json.tpl",
+          "target": "knowledge/knowledge.config.json"
+        }
+      ]
+    }
+  ]
 }

package/dist/cjs/capabilities/index.js

@@ -15,6 +15,19 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.commandSchema = exports.defineCommand = void 0;
+/**
+ * Capability registration surface: model capabilities, executable tools and host-selected
+ * invocations.
+ *
+ * These registries hold declarations only. Which capabilities a stage may use, whether a
+ * call is authorized, and what a payload means remain App decisions; this barrel provides
+ * the mechanisms that validate, seal and execute those declarations.
+ *
+ * Exports: the model capability registry (`model`), the executable tool registry and its
+ * sync/async invocation entry points (`tools`), host-selected invocation execution
+ * (`invocation`), and the Interaction Kit's protocol, command and handler definitions that
+ * shape and validate model-produced interactions.
+ */
 __exportStar(require("./model.js"), exports);
 __exportStar(require("./tools.js"), exports);
 __exportStar(require("./invocation.js"), exports);