@theokit/sdk 5.0.0-next.1 → 5.0.0-next.3

package/dist/internal/memory/storage/index.cjs

@@ -1,11 +1,11 @@
 'use strict';
 
-var chunkV6ZY4AX6_cjs = require('../../../chunk-V6ZY4AX6.cjs');
+var chunkVNDJS6I3_cjs = require('../../../chunk-VNDJS6I3.cjs');
 var chunkTMKTSYDS_cjs = require('../../../chunk-TMKTSYDS.cjs');
-var chunkLHSWHYF3_cjs = require('../../../chunk-LHSWHYF3.cjs');
+var chunkRXZSVNDG_cjs = require('../../../chunk-RXZSVNDG.cjs');
 require('../../../chunk-KRD3GQAA.cjs');
 require('../../../chunk-MUUQ2WFJ.cjs');
-require('../../../chunk-LKFET5A3.cjs');
+require('../../../chunk-LOHMT36V.cjs');
 require('../../../chunk-7A6535RA.cjs');
 require('../../../chunk-SA6K24NB.cjs');
 require('../../../chunk-GZV6AVRL.cjs');
@@ -19,23 +19,23 @@ require('../../../chunk-6LHQPOMI.cjs');
 
 Object.defineProperty(exports, "appendDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkV6ZY4AX6_cjs.appendDiaryEntry; }
+  get: function () { return chunkVNDJS6I3_cjs.appendDiaryEntry; }
 });
 Object.defineProperty(exports, "diaryPath", {
   enumerable: true,
-  get: function () { return chunkV6ZY4AX6_cjs.diaryPath; }
+  get: function () { return chunkVNDJS6I3_cjs.diaryPath; }
 });
 Object.defineProperty(exports, "entryHash", {
   enumerable: true,
-  get: function () { return chunkV6ZY4AX6_cjs.entryHash; }
+  get: function () { return chunkVNDJS6I3_cjs.entryHash; }
 });
 Object.defineProperty(exports, "readAllSqliteFacts", {
   enumerable: true,
-  get: function () { return chunkV6ZY4AX6_cjs.readAllSqliteFacts; }
+  get: function () { return chunkVNDJS6I3_cjs.readAllSqliteFacts; }
 });
 Object.defineProperty(exports, "renderDiaryEntry", {
   enumerable: true,
-  get: function () { return chunkV6ZY4AX6_cjs.renderDiaryEntry; }
+  get: function () { return chunkVNDJS6I3_cjs.renderDiaryEntry; }
 });
 Object.defineProperty(exports, "persistActiveMemoryTranscript", {
   enumerable: true,
@@ -43,95 +43,95 @@ Object.defineProperty(exports, "persistActiveMemoryTranscript", {
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_BYTES", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.MEMORY_INDEX_MAX_BYTES; }
+  get: function () { return chunkRXZSVNDG_cjs.MEMORY_INDEX_MAX_BYTES; }
 });
 Object.defineProperty(exports, "MEMORY_INDEX_MAX_LINES", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.MEMORY_INDEX_MAX_LINES; }
+  get: function () { return chunkRXZSVNDG_cjs.MEMORY_INDEX_MAX_LINES; }
 });
 Object.defineProperty(exports, "appendFact", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.appendFact; }
+  get: function () { return chunkRXZSVNDG_cjs.appendFact; }
 });
 Object.defineProperty(exports, "appendFactToMarkdown", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.appendFactToMarkdown; }
+  get: function () { return chunkRXZSVNDG_cjs.appendFactToMarkdown; }
 });
 Object.defineProperty(exports, "asMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.asMemoryRoot; }
+  get: function () { return chunkRXZSVNDG_cjs.asMemoryRoot; }
 });
 Object.defineProperty(exports, "claudeProjectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.claudeProjectMemoryDir; }
+  get: function () { return chunkRXZSVNDG_cjs.claudeProjectMemoryDir; }
 });
 Object.defineProperty(exports, "collectMarkdownFiles", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.collectMarkdownFiles; }
+  get: function () { return chunkRXZSVNDG_cjs.collectMarkdownFiles; }
 });
 Object.defineProperty(exports, "defaultIndexPath", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.defaultIndexPath; }
+  get: function () { return chunkRXZSVNDG_cjs.defaultIndexPath; }
 });
 Object.defineProperty(exports, "discoverSessionFiles", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.discoverSessionFiles; }
+  get: function () { return chunkRXZSVNDG_cjs.discoverSessionFiles; }
 });
 Object.defineProperty(exports, "discoverWikiFiles", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.discoverWikiFiles; }
+  get: function () { return chunkRXZSVNDG_cjs.discoverWikiFiles; }
 });
 Object.defineProperty(exports, "indexBudgetWarning", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.indexBudgetWarning; }
+  get: function () { return chunkRXZSVNDG_cjs.indexBudgetWarning; }
 });
 Object.defineProperty(exports, "lanceStoragePath", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.lanceStoragePath; }
+  get: function () { return chunkRXZSVNDG_cjs.lanceStoragePath; }
 });
 Object.defineProperty(exports, "memoryMdPath", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.memoryMdPath; }
+  get: function () { return chunkRXZSVNDG_cjs.memoryMdPath; }
 });
 Object.defineProperty(exports, "memoryReadRoots", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.memoryReadRoots; }
+  get: function () { return chunkRXZSVNDG_cjs.memoryReadRoots; }
 });
 Object.defineProperty(exports, "notesDir", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.notesDir; }
+  get: function () { return chunkRXZSVNDG_cjs.notesDir; }
 });
 Object.defineProperty(exports, "projectMemoryDir", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.projectMemoryDir; }
+  get: function () { return chunkRXZSVNDG_cjs.projectMemoryDir; }
 });
 Object.defineProperty(exports, "readFacts", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.readFacts; }
+  get: function () { return chunkRXZSVNDG_cjs.readFacts; }
 });
 Object.defineProperty(exports, "readFactsFromMarkdown", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.readFactsFromMarkdown; }
+  get: function () { return chunkRXZSVNDG_cjs.readFactsFromMarkdown; }
 });
 Object.defineProperty(exports, "resolveMemoryRoot", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.resolveMemoryRoot; }
+  get: function () { return chunkRXZSVNDG_cjs.resolveMemoryRoot; }
 });
 Object.defineProperty(exports, "sessionSummaryPath", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.sessionSummaryPath; }
+  get: function () { return chunkRXZSVNDG_cjs.sessionSummaryPath; }
 });
 Object.defineProperty(exports, "sessionsDir", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.sessionsDir; }
+  get: function () { return chunkRXZSVNDG_cjs.sessionsDir; }
 });
 Object.defineProperty(exports, "wikiDir", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.wikiDir; }
+  get: function () { return chunkRXZSVNDG_cjs.wikiDir; }
 });
 Object.defineProperty(exports, "writeSessionSummary", {
   enumerable: true,
-  get: function () { return chunkLHSWHYF3_cjs.writeSessionSummary; }
+  get: function () { return chunkRXZSVNDG_cjs.writeSessionSummary; }
 });
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map

package/dist/internal/memory/storage/index.js

@@ -1,9 +1,9 @@
-export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-WJXOICRC.js';
+export { appendDiaryEntry, diaryPath, entryHash, readAllSqliteFacts, renderDiaryEntry } from '../../../chunk-DX4RUWOK.js';
 export { persistActiveMemoryTranscript } from '../../../chunk-OR6XIWLB.js';
-export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-UNK4HNJH.js';
+export { MEMORY_INDEX_MAX_BYTES, MEMORY_INDEX_MAX_LINES, appendFact, appendFactToMarkdown, asMemoryRoot, claudeProjectMemoryDir, collectMarkdownFiles, defaultIndexPath, discoverSessionFiles, discoverWikiFiles, indexBudgetWarning, lanceStoragePath, memoryMdPath, memoryReadRoots, notesDir, projectMemoryDir, readFacts, readFactsFromMarkdown, resolveMemoryRoot, sessionSummaryPath, sessionsDir, wikiDir, writeSessionSummary } from '../../../chunk-J2SH3PNH.js';
 import '../../../chunk-KVNWIAO4.js';
 import '../../../chunk-FD2UT76F.js';
-import '../../../chunk-WFC26L6Y.js';
+import '../../../chunk-2XRAWOZZ.js';
 import '../../../chunk-EH6XD3FY.js';
 import '../../../chunk-UKMBRMGT.js';
 import '../../../chunk-JOFVLOFY.js';

package/dist/internal/persistence/index.cjs

@@ -7,7 +7,7 @@ var chunkDQZU7JK6_cjs = require('../../chunk-DQZU7JK6.cjs');
 var chunkBJUJT5ED_cjs = require('../../chunk-BJUJT5ED.cjs');
 var chunkZF2LDKQQ_cjs = require('../../chunk-ZF2LDKQQ.cjs');
 var chunkJLRLCBJ4_cjs = require('../../chunk-JLRLCBJ4.cjs');
-var chunkCEILSTWB_cjs = require('../../chunk-CEILSTWB.cjs');
+var chunkGGZ5GPE3_cjs = require('../../chunk-GGZ5GPE3.cjs');
 require('../../chunk-J7J7J2GN.cjs');
 require('../../chunk-6LHQPOMI.cjs');
 var promises = require('fs/promises');
@@ -111,15 +111,15 @@ Object.defineProperty(exports, "replaceFileAtomic", {
 });
 Object.defineProperty(exports, "displayTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.displayTheokitHome; }
+  get: function () { return chunkGGZ5GPE3_cjs.displayTheokitHome; }
 });
 Object.defineProperty(exports, "getProfilesRoot", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.getProfilesRoot; }
+  get: function () { return chunkGGZ5GPE3_cjs.getProfilesRoot; }
 });
 Object.defineProperty(exports, "getTheokitHome", {
   enumerable: true,
-  get: function () { return chunkCEILSTWB_cjs.getTheokitHome; }
+  get: function () { return chunkGGZ5GPE3_cjs.getTheokitHome; }
 });
 exports.casUpdate = casUpdate;
 exports.createExclusive = createExclusive;

package/dist/internal/persistence/index.js

@@ -5,7 +5,7 @@ export { applyWalWithFallback, isCorruptionError, openSqliteResilient } from '..
 export { JsonlParseError, appendJsonl, loadJsonl, readJsonlIds, withFileLock } from '../../chunk-TA3K7SBK.js';
 export { withCwdMutex } from '../../chunk-Q5EWJPRY.js';
 export { atomicWriteJson, atomicWriteText, replaceFileAtomic } from '../../chunk-3JHIFQ4I.js';
-export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-JTZ74HFD.js';
+export { displayTheokitHome, getProfilesRoot, getTheokitHome } from '../../chunk-67ADYSTW.js';
 import '../../chunk-ALUN2B4W.js';
 import '../../chunk-CZJ6Q7CW.js';
 import { open } from 'fs/promises';

package/dist/internal/persistence/paths.d.cts

@@ -26,6 +26,7 @@
  *
  * @internal
  */
+import { type CompatSourceDeclaration, type CompatSurface } from "../runtime/compat/foreign-config-sources.js";
 /**
  * Resolve the directory cwd-anchored SDK state lives in.
  *
@@ -48,12 +49,31 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * The project's own configuration root: `<cwd>/.theokit`, always — never `THEOKIT_HOME`.
+ *
+ * `THEOKIT_HOME` relocates cwd-anchored SDK STATE (sessions, credentials). A project's
+ * CONFIGURATION belongs to the repository: hooks, MCP servers, context sources, subagents, the
+ * personality a project declares, all committed to git and shared by a team. Following the
+ * override for any of them would move where a project's declared capabilities come from — a
+ * behaviour change wearing the costume of a refactor, which is exactly what this function exists
+ * to make impossible to do by accident: every config-class reader calls this instead of writing
+ * `join(cwd, ".theokit")` by hand.
+ *
+ * NOT for the `.claude/`-style foreign roots {@link adaptersForSurface} adds — those are additive,
+ * opt-in, and each has its own directory name.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function theokitConfigRoot(cwd: string): string;
 /**
  * Every directory a project's configuration may be read from, in precedence order.
  *
- * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
- * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
- * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ * `.theokit` first — via {@link theokitConfigRoot}, so it is NEVER affected by `THEOKIT_HOME` for
+ * the reason documented there — then `.claude`. The order is the whole contract: a project that
+ * declares a skill, agent or rule in both means the explicit namespace to win, and a caller merging
+ * these roots must therefore keep the FIRST occurrence of a name rather than the last.
  *
  * `.claude` is read because the formats already agree and only the location did not. Measured
  * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
@@ -63,19 +83,12 @@ export declare function getTheokitHome(cwd: string): string;
  * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
  * working — which is why this returns a LIST and not a single resolved answer.
  *
- * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
- * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
- * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
- * loaders that read these directories have always anchored on `cwd` directly. Honouring the
- * override here would silently move where a project's agents and skills come from, which is a
- * behaviour change wearing the costume of a refactor.
- *
  * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
  *
  * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
  * declares in `exports` but does NOT cover with its semver contract.
  */
-export declare function projectConfigRoots(cwd: string, sources?: readonly string[]): string[];
+export declare function projectConfigRoots(cwd: string, sources: readonly CompatSourceDeclaration[], surface: CompatSurface): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +102,7 @@ export declare function projectConfigRoots(cwd: string, sources?: readonly strin
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string, sources?: readonly string[]): string[];
+export declare function pluginBundleRoots(cwd: string, sources: readonly CompatSourceDeclaration[]): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/persistence/paths.d.ts

@@ -26,6 +26,7 @@
  *
  * @internal
  */
+import { type CompatSourceDeclaration, type CompatSurface } from "../runtime/compat/foreign-config-sources.js";
 /**
  * Resolve the directory cwd-anchored SDK state lives in.
  *
@@ -48,12 +49,31 @@
  * declares in `exports` but does NOT cover with its semver contract.
  */
 export declare function getTheokitHome(cwd: string): string;
+/**
+ * The project's own configuration root: `<cwd>/.theokit`, always — never `THEOKIT_HOME`.
+ *
+ * `THEOKIT_HOME` relocates cwd-anchored SDK STATE (sessions, credentials). A project's
+ * CONFIGURATION belongs to the repository: hooks, MCP servers, context sources, subagents, the
+ * personality a project declares, all committed to git and shared by a team. Following the
+ * override for any of them would move where a project's declared capabilities come from — a
+ * behaviour change wearing the costume of a refactor, which is exactly what this function exists
+ * to make impossible to do by accident: every config-class reader calls this instead of writing
+ * `join(cwd, ".theokit")` by hand.
+ *
+ * NOT for the `.claude/`-style foreign roots {@link adaptersForSurface} adds — those are additive,
+ * opt-in, and each has its own directory name.
+ *
+ * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
+ * declares in `exports` but does NOT cover with its semver contract.
+ */
+export declare function theokitConfigRoot(cwd: string): string;
 /**
  * Every directory a project's configuration may be read from, in precedence order.
  *
- * `.theokit` first, then `.claude`. The order is the whole contract: a project that declares a
- * skill, agent or rule in both means the explicit namespace to win, and a caller merging these
- * roots must therefore keep the FIRST occurrence of a name rather than the last.
+ * `.theokit` first — via {@link theokitConfigRoot}, so it is NEVER affected by `THEOKIT_HOME` for
+ * the reason documented there — then `.claude`. The order is the whole contract: a project that
+ * declares a skill, agent or rule in both means the explicit namespace to win, and a caller merging
+ * these roots must therefore keep the FIRST occurrence of a name rather than the last.
  *
  * `.claude` is read because the formats already agree and only the location did not. Measured
  * 2026-08-26: the SKILL.md frontmatter this SDK requires (`name` + `description`) is exactly what
@@ -63,19 +83,12 @@ export declare function getTheokitHome(cwd: string): string;
  * NOT a rename of `.theokit`, and not a migration. Both are read, so nothing that works today stops
  * working — which is why this returns a LIST and not a single resolved answer.
  *
- * Deliberately NOT affected by `THEOKIT_HOME`, and this is the one thing to remember about it.
- * That variable relocates cwd-anchored SDK *state* — sessions, the credential store. A project's
- * *configuration* is a property of the repository, not of where this SDK keeps its state, and the
- * loaders that read these directories have always anchored on `cwd` directly. Honouring the
- * override here would silently move where a project's agents and skills come from, which is a
- * behaviour change wearing the costume of a refactor.
- *
  * Creates nothing and checks nothing; either path may not exist, and the caller owns that.
  *
  * Semver-exempt: reachable via the `@theokit/sdk/internal/persistence` sub-path, which the package
  * declares in `exports` but does NOT cover with its semver contract.
  */
-export declare function projectConfigRoots(cwd: string, sources?: readonly string[]): string[];
+export declare function projectConfigRoots(cwd: string, sources: readonly CompatSourceDeclaration[], surface: CompatSurface): string[];
 /**
  * Every directory that may hold a plugin BUNDLE contributed by the Claude Code CLI.
  *
@@ -89,7 +102,7 @@ export declare function projectConfigRoots(cwd: string, sources?: readonly strin
  * reading a project's configuration, and guessing at someone's enablement would run code they
  * turned off.
  */
-export declare function pluginBundleRoots(cwd: string, sources?: readonly string[]): string[];
+export declare function pluginBundleRoots(cwd: string, sources: readonly CompatSourceDeclaration[]): string[];
 /**
  * The directory holding every profile: always `~/.theokit/profiles`, from `os.homedir()`.
  *

package/dist/internal/runtime/compat/compat-config-file.d.ts

@@ -0,0 +1,31 @@
+import type { CompatSourceDeclaration } from "./foreign-config-sources.js";
+/**
+ * Read `.theokit/config.json`'s `compat.adapters`, or `[]` when the file is absent, declares no
+ * `compat` section, or is malformed — the last two WARN on the diagnostics channel rather than
+ * failing silently, matching #526's fail-closed-and-say-so precedent for the code option.
+ *
+ * SYNC on purpose: the caller is `Agent`'s constructor, which resolves `compatSources` before any
+ * submanager exists to await a promise. `existsSync` is already how the same constructor checks for
+ * `.theokit`/`.claude`; a once-per-agent read of one small, optional JSON file is the same class of
+ * work, not a new one.
+ */
+export declare function readCompatConfigFile(cwd: string): CompatSourceDeclaration[];
+/**
+ * The one place `local.compatSources` — explicit code — and `.theokit/config.json` — the
+ * project's declared default — are reconciled. Every reader that needs `compatSources` (hooks,
+ * skills, plugins, subagents) calls THIS instead of writing `options.local?.compatSources ?? []`
+ * by hand: that pattern existed at five call sites before this function did, and every one of them
+ * silently meant "the file form doesn't exist" — the same duplication `theokitConfigRoot` closed
+ * one layer down, one layer up.
+ *
+ * PRECEDENCE: explicit code wins. A consumer passing `local.compatSources` made a decision at the
+ * call site; the file is the DEFAULT for callers who did not. This is not specified by #524 — it is
+ * this SDK's choice, made explicit here rather than left to whichever call site happened to be
+ * written first. It means a test or a one-off script can always override the file without editing
+ * or deleting it, which the reverse precedence would not allow.
+ */
+export declare function resolveCompatSources(options: {
+    local?: {
+        compatSources?: readonly CompatSourceDeclaration[];
+    };
+}, cwd: string): readonly CompatSourceDeclaration[];

package/dist/internal/runtime/compat/foreign-config-sources.d.ts

@@ -34,6 +34,36 @@ export declare const CLAUDE_CODE_SOURCE: ConfigSourceAdapter;
  * the whole reason this exists is that a directory name was never enough to describe a dialect.
  */
 export declare function adaptersFor(kinds: readonly string[]): ConfigSourceAdapter[];
+/**
+ * A surface a foreign source may be admitted to. The four the SDK reads a project directory for.
+ *
+ * They are listed separately because they carry very different risk, which is the whole reason
+ * #524 asks for per-surface control: a skill is text that enters the system prompt, a hook is
+ * command execution, a plugin is code loading. A consumer who wants their skills back has no
+ * reason to be handed the other two along with them.
+ */
+export type CompatSurface = "hooks" | "plugins" | "skills" | "subagents";
+/**
+ * A declared foreign source: a bare kind, or a kind with the surfaces it may be read for.
+ */
+export type CompatSourceDeclaration = string | {
+    readonly kind: string;
+    readonly import?: readonly string[];
+};
+/**
+ * The adapters admitted to ONE surface.
+ *
+ * Three rules, and each one fails closed:
+ *
+ * - A bare string admits every surface. It is what `5.0.0-next.1` published, so narrowing it
+ *   silently would turn a working opt-in into a no-op — the exact defect #524 is about, one level
+ *   up.
+ * - An object with no `import` admits nothing. The issue's own rule, and safe to apply strictly
+ *   because the object form is new and nobody can be depending on it.
+ * - An unrecognised surface name is dropped rather than matched loosely, for the same reason an
+ *   unrecognised KIND is dropped in {@link adaptersFor}: a typo must not silently widen access.
+ */
+export declare function adaptersForSurface(sources: readonly CompatSourceDeclaration[], surface: CompatSurface): ConfigSourceAdapter[];
 /**
  * The adapter whose directory an absolute config path sits under, or `undefined` for a path that
  * belongs to no registered dialect.
@@ -83,4 +113,4 @@ export declare function undefinedVariablesIn(command: string, supplied: Readonly
  *
  * So it goes on the interceptable channel, for the reader holding the question it answers.
  */
-export declare function reportUndeclaredSources(cwd: string, declared: readonly string[]): void;
+export declare function reportUndeclaredSources(cwd: string, declared: readonly CompatSourceDeclaration[]): void;

package/dist/internal/runtime/hooks/hooks-executor.d.ts

@@ -1,3 +1,4 @@
+import type { CompatSourceDeclaration } from "../compat/foreign-config-sources.js";
 export interface HookCommand {
     command: string;
     /** Optional matcher restricting the hook to specific tools (regex). */
@@ -39,7 +40,7 @@ export declare class HooksExecutor {
     private config;
     constructor(cwd: string, 
     /** Declared foreign dialects (#524). Empty reads `.theokit/` only. */
-    compatSources?: readonly string[]);
+    compatSources?: readonly CompatSourceDeclaration[]);
     initialize(settingSourcesIncludeProject: boolean): Promise<void>;
     /** Fire every hook registered for `event` and aggregate the decisions. */
     run(payload: HookPayload): Promise<HookExecutionResult>;

package/dist/internal/runtime/plugin-loader/plugin-bundles.d.ts

@@ -6,6 +6,7 @@
  *
  * @internal
  */
+import type { CompatSourceDeclaration } from "../compat/foreign-config-sources.js";
 /**
  * Every plugin folder under the project's plugin roots.
  *
@@ -18,4 +19,4 @@
  */
 export declare function pluginBundleDirs(cwd: string, 
 /** Declared foreign dialects (#524). Empty reads `.theokit/plugins` only. */
-compatSources?: readonly string[]): Promise<string[]>;
+compatSources?: readonly CompatSourceDeclaration[]): Promise<string[]>;

package/dist/project.cjs

@@ -1,6 +1,6 @@
 'use strict';
 
-var chunkLKFET5A3_cjs = require('./chunk-LKFET5A3.cjs');
+var chunkLOHMT36V_cjs = require('./chunk-LOHMT36V.cjs');
 var chunkJLRLCBJ4_cjs = require('./chunk-JLRLCBJ4.cjs');
 var chunkJ7J7J2GN_cjs = require('./chunk-J7J7J2GN.cjs');
 require('./chunk-6LHQPOMI.cjs');
@@ -11,7 +11,7 @@ var DEFAULT_FILENAME = "THEO.md";
 async function readProjectInstructions(cwd, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
   const scope = options?.scope ?? "nearest";
-  const paths = chunkLKFET5A3_cjs.walkUpForFile(cwd, filename, options?.stopDir);
+  const paths = chunkLOHMT36V_cjs.walkUpForFile(cwd, filename, options?.stopDir);
   const files = [];
   for (const path of paths) {
     try {
@@ -30,7 +30,7 @@ function reduceContent(files, scope) {
 }
 async function writeProjectInstructions(cwd, content, options) {
   const filename = options?.filename ?? DEFAULT_FILENAME;
-  if (!chunkLKFET5A3_cjs.isSafePattern(filename)) {
+  if (!chunkLOHMT36V_cjs.isSafePattern(filename)) {
     throw new chunkJ7J7J2GN_cjs.ConfigurationError(
       `writeProjectInstructions: unsafe filename ${JSON.stringify(filename)} (no path traversal, separators, or absolute paths)`,
       { code: "unsafe_filename" }

package/dist/project.js

@@ -1,4 +1,4 @@
-import { walkUpForFile, isSafePattern } from './chunk-WFC26L6Y.js';
+import { walkUpForFile, isSafePattern } from './chunk-2XRAWOZZ.js';
 import { replaceFileAtomic } from './chunk-3JHIFQ4I.js';
 import { ConfigurationError } from './chunk-ALUN2B4W.js';
 import './chunk-CZJ6Q7CW.js';

package/dist/{sdk-agent-Dxjb0IfM.d.cts → sdk-agent-BOiKqOgL.d.cts}

@@ -613,10 +613,27 @@ interface GoalOptions {
 interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -660,6 +677,16 @@ interface SDKAgentSkills {
 interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when

package/dist/{sdk-agent-ldzpyAaF.d.ts → sdk-agent-D4a_BR_6.d.ts}

@@ -613,10 +613,27 @@ interface GoalOptions {
 interface SystemPromptSkillRef {
     name: string;
     description: string;
+    /**
+     * Where this skill came from: the absolute path to its `SKILL.md` for a skill read from disk,
+     * or the synthetic `inline://<name>` marker `createSkill` stamps on a code-defined one (see
+     * `create-skill.ts`) — there is no third case, so this is populated for every skill `list()`
+     * returns.
+     *
+     * It is the ORIGIN and NOT the body: `list()` stays lean by contract, and a skill's instructions
+     * are reachable only through {@link SDKAgentSkills.get}. What this adds is the answer to
+     * usetheokit/theokit-sdk#524's visibility question — which root a skill came from, so a listing
+     * can show that one arrived from `.claude/skills/` rather than the project's own directory, or
+     * that it was never on disk at all.
+     *
+     * Typed optional rather than required because {@link SystemPromptSkillRef} is the shape any
+     * future skill producer returns, and this SDK should not assert every one of them can name an
+     * origin.
+     */
+    source?: string;
 }
 /**
  * A skill resolved WITH its body, returned by {@link SDKAgentSkills.get}. Unlike
- * {@link SystemPromptSkillRef} (name + description only), this carries the full
+ * {@link SystemPromptSkillRef}, which carries metadata only, this carries the full
  * `instructions` — read from the SKILL.md for filesystem skills or the inline
  * `createSkill` body. @public
  */
@@ -660,6 +677,16 @@ interface SDKAgentSkills {
 interface SDKPluginMetadata {
     name: string;
     description?: string;
+    /**
+     * Absolute path the plugin manifest was read from.
+     *
+     * The runtime has ALWAYS returned this — `agent.plugins.list()` hands back the internal
+     * `PluginMetadata`, whose own docblock says it carries provenance "so callers can audit where the
+     * plugin came from". This type simply did not declare it, so the caller received the field and
+     * the compiler denied it existed. Declaring it is what makes the audit usetheokit/theokit-sdk#524
+     * asks for reachable in typed code.
+     */
+    source?: string;
 }
 /**
  * Public plugin listing handle exposed as `agent.plugins`. Populated when

package/dist/subagents-loader-TPZLTXYZ.cjs

@@ -0,0 +1,16 @@
+'use strict';
+
+var chunkSYVWE64W_cjs = require('./chunk-SYVWE64W.cjs');
+require('./chunk-GGZ5GPE3.cjs');
+require('./chunk-HW7SEELD.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "loadSubagents", {
+  enumerable: true,
+  get: function () { return chunkSYVWE64W_cjs.loadSubagents; }
+});
+//# sourceMappingURL=subagents-loader-TPZLTXYZ.cjs.map
+//# sourceMappingURL=subagents-loader-TPZLTXYZ.cjs.map

package/dist/{subagents-loader-YWFE7KYE.cjs.map → subagents-loader-TPZLTXYZ.cjs.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-YWFE7KYE.cjs"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-TPZLTXYZ.cjs"}

package/dist/subagents-loader-Y6JFYXAY.js

@@ -0,0 +1,7 @@
+export { loadSubagents } from './chunk-4S5TWFIZ.js';
+import './chunk-67ADYSTW.js';
+import './chunk-JNAA4G4H.js';
+import './chunk-ALUN2B4W.js';
+import './chunk-CZJ6Q7CW.js';
+//# sourceMappingURL=subagents-loader-Y6JFYXAY.js.map
+//# sourceMappingURL=subagents-loader-Y6JFYXAY.js.map

package/dist/{subagents-loader-LSKM2UIK.js.map → subagents-loader-Y6JFYXAY.js.map}

@@ -1 +1 @@
-{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-LSKM2UIK.js"}
+{"version":3,"sources":[],"names":[],"mappings":"","file":"subagents-loader-Y6JFYXAY.js"}