cyber-agentkit 1.1.0 → 2.0.0

package/dist/reference-where-BsBpwLyg.d.ts

@@ -0,0 +1,735 @@
+import { t as HarnessId } from "./harness-id-BgKL-x6C.js";
+//#region src/harness/platform.d.ts
+/**
+ * An operating-system platform, spelled as `process.platform` reports it.
+ *
+ * The queries branch on `darwin`, `linux`, and `win32`; every other platform follows the POSIX
+ * (`linux`) layout. The union lists every value Node.js reports, so `process.platform` is assignable
+ * to it, but it is declared here rather than as `NodeJS.Platform` so the published types do not
+ * depend on `@types/node`.
+ */
+type Platform = 'aix' | 'android' | 'cygwin' | 'darwin' | 'freebsd' | 'haiku' | 'linux' | 'netbsd' | 'openbsd' | 'sunos' | 'win32';
+//#endregion
+//#region src/assets/asset-layers.d.ts
+/** Where an asset lives. Listed highest first. */
+type AssetTier = 'managed' | 'project' | 'user' | 'plugin' | 'default';
+/** A fault that never stops a name from resolving. The `code` is stable; the `message` is for a person. */
+type AssetWarning = {
+  code: 'default-folder-missing' | 'default-in-tier' | 'file-ignored' | 'selection-invalid';
+  message: string;
+};
+type AssetPlugin = {
+  /** Its manifest `name`, which a qualified `<plugin>/<name>` uses. */
+  name: string;
+  /** The plugin root, which holds its `assets/`. */
+  root: string;
+};
+type AssetLayerOptions = {
+  root: string;
+  home: string;
+  platform: Platform;
+  /** The plugin running the resolver. Its `assets/` is the first plugin layer. */
+  plugin?: AssetPlugin | undefined;
+  /** The calling skill's folder: its `assets/<name>.<ext>` forms the `default` tier. */
+  defaultSkill?: string | undefined;
+  /** Detects the harness and reads its settings. Defaults to `process.env`. */
+  env?: Readonly<Record<string, string | undefined>>;
+};
+//#endregion
+//#region src/skills/skill-folder.d.ts
+/**
+ * The `name` in a skill folder's `SKILL.md`, else the folder's own name; `undefined` when the folder
+ * holds no `SKILL.md`. A package manager may link a skill under another folder name, such as pnpm's
+ * `pnpm-<package>-<skill>` (E-PM-PNPM-4), so the folder name is only a fallback.
+ */
+declare function skillName(folder: string): string | undefined;
+type FoundSkill = {
+  /** The `name` its `SKILL.md` gives. */
+  name: string;
+  /** The folder, with symlinks resolved. */
+  folder: string;
+};
+/**
+ * The skills in each folder: the folder itself when it holds a `SKILL.md`, else each skill directly
+ * under it, one level deep. A symlinked skill folder is followed, since pnpm and `npx skills` link
+ * skills rather than copy them (E-PM-SK-2, E-PM-SK-7); one real folder reached twice is listed once.
+ */
+declare function skillsIn(folders: readonly string[]): FoundSkill[];
+//#endregion
+//#region src/references/reference-codes.d.ts
+/**
+ * Every code a reference command or library function emits, and this table is its one home: one code,
+ * one kind, one description (R104). Adding a code is not breaking; removing or renaming one is.
+ *
+ * A kind fixes the exit value of a command that ends on the code (R43): a name `status` and a
+ * `notice` are answers (exit 0), a `refused` request is a state of the files (exit 1), a `usage`
+ * error is a wrong invocation (exit 2), and a `warning` never changes the exit value.
+ *
+ * A failed `check` is an entry in its result, not a code here: its `check` is the check's name.
+ */
+declare const referenceCodes: {
+  readonly 'reference-missing': {
+    readonly kind: 'status';
+    readonly when: 'no tier holds the name, or the plugin a qualified name asks for is not installed (UC1.1)';
+  };
+  readonly 'reference-removed': {
+    readonly kind: 'status';
+    readonly when: 'a `missing` name a `remove` turned off (UC1.1, R49)';
+  };
+  readonly 'reference-ambiguous': {
+    readonly kind: 'status';
+    readonly when: 'contributions that cannot be put in one order, or a name two names list as an alias (UC1.2, R98)';
+  };
+  readonly 'reference-invalid': {
+    readonly kind: 'status';
+    readonly when: 'not a name (UC1.3, R1)';
+  };
+  readonly 'frontmatter-invalid': {
+    readonly kind: 'warning';
+    readonly when: 'malformed frontmatter (R105)';
+  };
+  readonly 'merge-unknown': {
+    readonly kind: 'warning';
+    readonly when: 'an unknown `merge` value (R7)';
+  };
+  readonly 'marker-unknown': {
+    readonly kind: 'warning';
+    readonly when: 'an unknown merge marker (R7)';
+  };
+  readonly 'marker-unmatched': {
+    readonly kind: 'warning';
+    readonly when: 'an explicit marker that matches nothing below (R7)';
+  };
+  readonly 'heading-repeated': {
+    readonly kind: 'warning';
+    readonly when: 'a document repeating a heading (R7)';
+  };
+  readonly 'remove-body-ignored': {
+    readonly kind: 'warning';
+    readonly when: 'a `remove` with a body (R49)';
+  };
+  readonly 'extends-invalid': {
+    readonly kind: 'warning';
+    readonly when: 'a malformed `extends` (R106)';
+  };
+  readonly 'extends-self': {
+    readonly kind: 'warning';
+    readonly when: 'a plugin listing itself (R54)';
+  };
+  readonly 'extends-step-missing': {
+    readonly kind: 'warning';
+    readonly when: 'a step that cannot be used (R55)';
+  };
+  readonly 'extends-all-missing': {
+    readonly kind: 'warning';
+    readonly when: 'every step cannot be used (R55)';
+  };
+  readonly 'extends-not-used': {
+    readonly kind: 'warning';
+    readonly when: 'a lower `extends` that builds a different stack (R53); picks written under a managed `extends` that builds it (R109)';
+  };
+  readonly 'section-not-held': {
+    readonly kind: 'warning';
+    readonly when: 'a `sections` entry the plugin does not hold (R52)';
+  };
+  readonly 'default-not-selected': {
+    readonly kind: 'warning';
+    readonly when: 'a plugin answering over the default with no `extends` naming either, and no own `extends` of the plugin naming `default` (R56)';
+  };
+  readonly 'plugin-not-selected': {
+    readonly kind: 'warning';
+    readonly when: 'a plugin holding the name that the `repo` or `user` `extends` building the stack neither places nor declines (R113)';
+  };
+  readonly 'default-folder-missing': {
+    readonly kind: 'warning';
+    readonly when: 'a `--default` folder that does not exist (R41)';
+  };
+  readonly 'default-in-tier': {
+    readonly kind: 'warning';
+    readonly when: 'a `<name>.default.md` in a tier folder (R51)';
+  };
+  readonly 'file-ignored': {
+    readonly kind: 'warning';
+    readonly when: "a second file for a name in one folder, one under an older name beside the new name's included (R67, R97)";
+  };
+  readonly 'format-mismatch': {
+    readonly kind: 'warning';
+    readonly when: 'a Markdown contribution above a non-Markdown one (R68)';
+  };
+  readonly 'metadata-ignored': {
+    readonly kind: 'warning';
+    readonly when: 'a misplaced metadata file, or a body, `merge`, or `implements` in one (R94)';
+  };
+  readonly 'project-section-key-ignored': {
+    readonly kind: 'warning';
+    readonly when: '`merge`, `extends`, `implements`, or `aliases` in a project section, or dropped from one `create --in --template` writes (R27, R110)';
+  };
+  readonly 'interface-not-composed': {
+    readonly kind: 'warning';
+    readonly when: '`extends`, `merge`, or a higher copy on an interface document (R14)';
+  };
+  readonly 'interface-check': {
+    readonly kind: 'warning';
+    readonly when: 'a loaded document failing its interface check (R37)';
+  };
+  readonly 'base-moved': {
+    readonly kind: 'warning';
+    readonly when: '`check` on a plugin or default file whose extended base has a newer version (R86)';
+  };
+  readonly 'reference-stale': {
+    readonly kind: 'warning';
+    readonly when: 'a generated document or project section with a changed or missing source (R101)';
+  };
+  readonly 'reference-renamed': {
+    readonly kind: 'warning';
+    readonly when: "a name or file under an older name, or an interface's older id (R96, R97)";
+  };
+  readonly 'alias-not-used': {
+    readonly kind: 'warning';
+    readonly when: 'an alias a name holds as its own (R98)';
+  };
+  readonly 'alias-invalid': {
+    readonly kind: 'warning';
+    readonly when: 'an invalid or misplaced alias (R96)';
+  };
+  readonly 'project-section-not-markdown': {
+    readonly kind: 'warning';
+    readonly when: 'a Markdown project section for a name whose main document is not Markdown, or a non-Markdown file in a project folder (R99)';
+  };
+  readonly 'reference-hidden': {
+    readonly kind: 'warning';
+    readonly when: 'a file hidden by a `replace` or `remove` above it: one `create` or `customize` wrote (R26), or one `check` finds (R112)';
+  };
+  readonly 'repo-hides-user': {
+    readonly kind: 'warning';
+    readonly when: "a `user` file this repository's `repo` contribution hides (R26, R112)";
+  };
+  readonly 'root-missing': {
+    readonly kind: 'refused';
+    readonly when: 'a `--root` that does not exist (R12)';
+  };
+  readonly 'file-unreadable': {
+    readonly kind: 'refused';
+    readonly when: 'a `--request` or `--body` file that cannot be read (R81, R82)';
+  };
+  readonly 'folder-invalid': {
+    readonly kind: 'refused';
+    readonly when: 'a `--plugin` or `--default` folder that does not qualify (R24)';
+  };
+  readonly 'file-exists': {
+    readonly kind: 'refused';
+    readonly when: '`create` on a file with a body, or where the target folder holds a file answering the name in another form (R60)';
+  };
+  readonly 'extends-replace': {
+    readonly kind: 'refused';
+    readonly when: 'a `--plugin` or `--default` file extending a plugin with `replace` (R103)';
+  };
+  readonly 'interface-invalid': {
+    readonly kind: 'refused';
+    readonly when: '`--implements` with an unknown interface (R28, R111)';
+  };
+  readonly 'interface-unknown': {
+    readonly kind: 'refused';
+    readonly when: '`implementations` of an unknown interface (R35)';
+  };
+  readonly 'template-title': {
+    readonly kind: 'refused';
+    readonly when: 'a title template (R32)';
+  };
+  readonly 'template-invalid': {
+    readonly kind: 'refused';
+    readonly when: 'an unreadable template, or one whose frontmatter is not a mapping (R32)';
+  };
+  readonly 'extends-file-invalid': {
+    readonly kind: 'refused';
+    readonly when: 'an `--extends-file` that is unreadable or not a YAML `extends` list (R79)';
+  };
+  readonly 'step-invalid': {
+    readonly kind: 'refused';
+    readonly when: 'a step neither `default` nor a plugin holding the name (R79)';
+  };
+  readonly 'no-selection': {
+    readonly kind: 'notice';
+    readonly when: '`--extends none` with no `extends` there: a no-op (R80)';
+  };
+  readonly 'body-not-generated': {
+    readonly kind: 'refused';
+    readonly when: '`--request` on a body that records no request (R82)';
+  };
+  readonly 'pick-required': {
+    readonly kind: 'refused';
+    readonly when: '`--request` without `--extends` on an `ambiguous` name (R82)';
+  };
+  readonly 'name-outside-interface': {
+    readonly kind: 'refused';
+    readonly when: "`customize --implements` on a name outside the interface's namespace (R111)";
+  };
+  readonly 'implements-required': {
+    readonly kind: 'refused';
+    readonly when: "`--request` without `--implements` on a `missing` name under a found interface's namespace (R111)";
+  };
+  readonly 'in-not-markdown': {
+    readonly kind: 'refused';
+    readonly when: '`create --in` or `customize --in` for a name whose main document is not Markdown, which has no project sections (R82)';
+  };
+  readonly 'in-folder-missing': {
+    readonly kind: 'refused';
+    readonly when: '`--in` on `create`, `customize`, or `delete` naming a folder that does not exist (J8)';
+  };
+  readonly 'in-folder-ignored': {
+    readonly kind: 'refused';
+    readonly when: '`--in` on `create`, `customize`, or `delete` naming a folder git ignores (J8)';
+  };
+  readonly 'no-file': {
+    readonly kind: 'notice';
+    readonly when: '`delete` with no file there: a no-op (R30)';
+  };
+  readonly 'name-missing': {
+    readonly kind: 'usage';
+    readonly when: 'a command that needs a name, given none (UC1.7)';
+  };
+  readonly 'name-invalid': {
+    readonly kind: 'usage';
+    readonly when: 'a write given a string that is not a name, such as `../x` (J1, R1)';
+  };
+  readonly 'reference-qualified': {
+    readonly kind: 'usage';
+    readonly when: 'a qualified name given to a write (R25)';
+  };
+  readonly 'query-missing': {
+    readonly kind: 'usage';
+    readonly when: '`search` with an empty query (UC3.2)';
+  };
+  readonly 'change-missing': {
+    readonly kind: 'usage';
+    readonly when: '`customize` with neither `--extends` nor `--request` (R82)';
+  };
+  readonly 'options-conflict': {
+    readonly kind: 'usage';
+    readonly when: 'flags that exclude each other, such as two of `--scope`, `--in`, `--plugin`, `--default` on `create` and `delete`, `--scope` with `--in` on `customize`, or `--merge` or `--extends` with `--in` (R24, R27, R82)';
+  };
+  readonly 'options-missing': {
+    readonly kind: 'usage';
+    readonly when: 'a flag given without the one it needs: `--request` without `--body`, or the reverse (R82)';
+  };
+  readonly 'option-invalid': {
+    readonly kind: 'usage';
+    readonly when: 'a flag given a value it does not accept, such as an unknown `--merge` operation (R27)';
+  };
+  readonly 'in-not-below-root': {
+    readonly kind: 'usage';
+    readonly when: '`--in` naming the root or a folder outside it (R24)';
+  };
+  readonly 'remove-with-template': {
+    readonly kind: 'usage';
+    readonly when: '`--merge remove` with `--template` (R27)';
+  };
+  readonly 'template-with-implements': {
+    readonly kind: 'usage';
+    readonly when: '`--template` with `--implements` (R28)';
+  };
+};
+type ReferenceCodeKind = 'status' | 'warning' | 'refused' | 'notice' | 'usage';
+type ReferenceCode = keyof typeof referenceCodes;
+type CodesOf<K extends ReferenceCodeKind> = { [C in ReferenceCode]: (typeof referenceCodes)[C]['kind'] extends K ? C : never; }[ReferenceCode];
+/** The code of a name that is not `found`. */
+type ReferenceStatusCode = CodesOf<'status'>;
+type ReferenceWarningCode = CodesOf<'warning'>;
+/** The code of a no-op's answer, carried in the result. */
+type ReferenceNoticeCode = CodesOf<'notice'>;
+/** The code of a request that cannot complete (exit 1) or was called wrongly (exit 2). */
+type ReferenceErrorCode = CodesOf<'refused' | 'usage'>;
+/** The exit value of a command that ends on `code`; `undefined` for a warning, which leaves it alone. */
+declare function referenceCodeExit(code: ReferenceCode): 0 | 1 | 2 | undefined;
+/**
+ * A fault that never stops a name from resolving. The `code` is stable; the `message` is for a
+ * person and is not a contract.
+ */
+type ReferenceWarning = {
+  code: ReferenceWarningCode;
+  message: string;
+};
+//#endregion
+//#region src/references/reference-projects.d.ts
+/** A folder strictly below the root holding a `.agents/references/`, whose files are that folder's project sections. */
+type ProjectFolder = {
+  /** The folder, relative to the root, with `/` between segments. */
+  folder: string;
+  /** Its `.agents/references/` folder, absolute. */
+  dir: string;
+};
+/** What one discovery found below a root: the folders to read, the ones git ignores, and the files git lists. */
+type ProjectFolders = {
+  /** The folders whose `.agents/references/` git does not ignore, in path order. */
+  folders: ProjectFolder[];
+  /**
+   * The folders whose `.agents/references/` git ignores, in path order: one an ignore file names, or
+   * one whose every listed file is ignored. A folder inside an ignored folder is not looked for, so
+   * discovery never walks an ignored tree such as `node_modules/`.
+   */
+  ignored: ProjectFolder[];
+  /** Each file below the root git lists and does not ignore, relative with `/`; `undefined` outside git, where nothing is ignored. */
+  listed?: ReadonlySet<string> | undefined;
+  /**
+   * The folders strictly below the root holding a `package.json` git does not ignore, in path order,
+   * relative with `/`. Outside git, every one not inside a `node_modules/` folder.
+   */
+  packages: string[];
+};
+/** One discovery per root, so one run asks git once per root. */
+type ProjectFolderCache = Map<string, ProjectFolders>;
+//#endregion
+//#region src/references/reference-sources.d.ts
+/**
+ * A contribution a generated document is built from (K34): a plugin, as `{plugin, version}`, or a
+ * skill's default, as `{default: <skill>}`, with the plugin and version of the plugin that ships the
+ * skill, when one does. A source with no version is stale only when it is gone.
+ */
+type ReferenceSource = {
+  plugin: string;
+  version?: string;
+} | {
+  default: string;
+  plugin?: string;
+  version?: string;
+};
+/**
+ * What a generated document records in its frontmatter (K25): each source with its plugin's version,
+ * and the customizer's request. A project section records these alone; a whole document from an
+ * interface's stub records `implements` and the request, and no sources.
+ */
+type GeneratedRecord = {
+  sources?: ReferenceSource[];
+  request?: string;
+};
+/** A plugin installed where the name resolves, with the version load compares a recorded one to (C5). */
+type ReferenceSourcePlugin = {
+  plugin: string;
+  version?: string | undefined;
+  origin?: PluginOrigin | undefined;
+};
+/** One recorded source, as the trace reports it: its recorded and installed versions, and whether it changed. */
+type ReferenceTraceSource = {
+  plugin?: string;
+  default?: string;
+  recorded?: string;
+  installed?: string;
+  /** `current`; `changed` when the installed plugin's version differs; `missing` when the source is gone. */
+  status: 'current' | 'changed' | 'missing';
+};
+//#endregion
+//#region src/references/reference-layers.d.ts
+/**
+ * Where a contribution lives. Listed highest first; the stack (plugins and `default`) is ordered by
+ * `extends`. `project` is a `.agents/references/` folder below the root, which adds a project section
+ * rather than a layer.
+ */
+type ReferenceTier = 'managed' | 'repo' | 'project' | 'user' | 'plugin' | 'default';
+/**
+ * How a plugin came to be read: the plugin running the resolver, one a harness enabled, a dependency
+ * of the root's `package.json`, or one a `package.json` below the root declares, which adds project
+ * sections for its folder and no layer (K36).
+ */
+type PluginOrigin = 'host' | 'enabled' | 'dependency' | 'package';
+type ReferenceLayer = {
+  tier: ReferenceTier;
+  /** The folder read for contributions. */
+  dir: string;
+  /** The plugin tier: the plugin's manifest `name`, which a qualified `<plugin>/<name>` uses. */
+  plugin?: string | undefined;
+  /** The default tier: the skill's `SKILL.md` `name`. */
+  skill?: string | undefined;
+  /** The plugin tier: how the plugin came to be read. */
+  origin?: PluginOrigin | undefined;
+  /** The plugin tier: the installed version, from the install record, else the plugin manifest, else `package.json`. */
+  version?: string | undefined;
+  /** Set when the layer is never read, and why: policy held in MDM, a plugin with no install folder. */
+  skipped?: string | undefined;
+  /** Raised on every name resolved through this layer, such as a `--default` folder that does not exist. */
+  warning?: ReferenceWarning | undefined;
+};
+type ReferenceLayerOptions = {
+  /**
+   * The repository root. Its `.agents/references/` is the `repo` tier and its `package.json` names the
+   * dependency plugins. When given, it must exist, or the call throws `root-missing`. Defaults to the
+   * nearest folder at or above `cwd` holding `.git`, else `cwd`.
+   */
+  root?: string | undefined;
+  /** The working folder the root is found from. Defaults to `process.cwd()`. */
+  cwd?: string | undefined;
+  home: string;
+  platform: Platform;
+  /**
+   * The plugin running the resolver. Its `references/` is the first plugin layer, and its install,
+   * when a harness has it enabled, is not read a second time.
+   */
+  plugin?: ReferencePlugin | undefined;
+  /** The calling skill's folder: its `references/<name>.default.md` forms the `default` tier. */
+  defaultSkill?: string | undefined;
+  /** Detects the harness and reads its settings. Defaults to `process.env`. */
+  env?: Readonly<Record<string, string | undefined>>;
+};
+type ReferencePlugin = {
+  /** Its manifest `name`, which a qualified `<plugin>/<name>` uses. */
+  name: string;
+  /** The plugin root, which holds its `references/`. */
+  root: string;
+};
+type ReferenceLayers = {
+  /** Highest first: managed, repo, user, plugin, default. */
+  layers: ReferenceLayer[];
+  /** The repository root the layers were read from. Its folders below hold the project sections. */
+  root?: string | undefined;
+  /** The project folders found below the root, kept for the run so git is asked once. */
+  projects?: ProjectFolderCache | undefined;
+  /** The harnesses detected, whose managed folders and enabled plugins were read. */
+  harnesses: readonly HarnessId[];
+  /** The installed skills that hold a default, which `list`, `search`, and `check` reach. */
+  skills?: SkillDefaults | undefined;
+  /**
+   * Every plugin read, with its installed version and origin, whether or not it ships `references/`:
+   * a generated document's recorded sources are compared to these (R101).
+   */
+  plugins?: ReferenceSourcePlugin[] | undefined;
+};
+/** The installed skills holding a default contribution, found in the skill folders the detected harnesses read. */
+type SkillDefaults = {
+  skills: FoundSkill[];
+  /** Why some skills' defaults are not listed: no harness detected, or one whose skill folders are not verified. */
+  unverified?: string | undefined;
+};
+declare function repoReferencesDir(root: string): string;
+declare function userReferencesDir(home: string): string;
+/** The `default` tier for the skill at `folder`; a folder that does not exist warns and adds no contribution. */
+declare function defaultLayer(folder: string): ReferenceLayer;
+declare function referenceLayers({ root: given, cwd, home, platform, plugin, defaultSkill, env }: ReferenceLayerOptions): Promise<ReferenceLayers>;
+//#endregion
+//#region src/references/reference-document.d.ts
+/**
+ * How a contribution applies over what is below it. `replace` puts it in place of everything below;
+ * `patch` keeps what is below and puts each section's text in place of the text it matches;
+ * `combine` keeps what is below and adds each section's text after the text it matches; `remove`
+ * drops what is below.
+ */
+type MergeOperation = 'replace' | 'patch' | 'combine' | 'remove';
+/** Which contribution supplied a section's text, and how. */
+type SectionSource = {
+  contribution: string;
+  operation: MergeOperation;
+};
+//#endregion
+//#region src/references/reference-format.d.ts
+/** The format of a reference file: `markdown`, or the extension of a data file. */
+type ReferenceFormat = 'markdown' | 'json' | 'yaml' | 'toml' | 'txt';
+//#endregion
+//#region src/references/reference-name.d.ts
+type ReferenceName = {
+  /** As asked. */
+  raw: string;
+  /** The bare name. */
+  name: string;
+  /** The plugin a qualified `<plugin>/<name>` asks for, by its manifest's `name`. */
+  plugin?: string | undefined;
+  /** Why the value is not a reference name. Set only on an invalid one; nothing is read for it. */
+  invalid?: string | undefined;
+};
+/**
+ * Rejects rather than sanitizes — silently answering a different question is how untrusted input
+ * reads a file outside a layer. The plugin qualifier is only ever compared with plugin names, never
+ * joined into a path. A bad name comes back `invalid`, never thrown, so the other names still resolve.
+ */
+declare function parseReferenceName(value: string): ReferenceName;
+//#endregion
+//#region src/references/reference-project-sections.d.ts
+/** A project section as load delivers it: what one folder below the root adds after the main document. */
+type ResolvedProjectSection = {
+  /** The folder it applies to, relative to the root, `/`-separated, with no leading `./` or trailing slash. */
+  folder: string;
+  /** The file that answered. */
+  path: string;
+  /** Its text, the managed contribution applied over it, with its own heading levels. */
+  content: string;
+  /** Its frontmatter, less the keys a project section does not carry. */
+  metadata: Record<string, unknown>;
+  /** Set when a package plugin (K36) supplied it: that plugin's manifest `name`. */
+  plugin?: string;
+};
+/** A project section the trace reports: one delivered, or one in a folder git ignores. */
+type ReferenceTraceProjectSection = {
+  folder: string;
+  /** The file matched, or the folder checked when the folder is ignored. */
+  path: string;
+  /** The file that answered, relative to the folder: `<name>.md` or `<name>/README.md`. */
+  file?: string;
+  /** Its frontmatter as written. */
+  frontmatter?: Record<string, unknown>;
+  /** `used`; `stale`; `shadowed by <managed> (replace|remove)`; `not used (...)`; or `not read (ignored)`. */
+  outcome: string;
+  /** A generated section: each source of the main document it was written against, recorded and installed (R9). */
+  sources?: ReferenceTraceSource[];
+  /** A generated section: the request it records. */
+  request?: string;
+  /** When the managed contribution changed it: each section by heading path, with what supplied its text. */
+  sections?: ReferenceTraceSection[];
+  /** A section filed under an older name of the name (R97): that older name. */
+  alias?: string;
+  /** Set when a package plugin (K36) supplied it: that plugin's manifest `name`. */
+  plugin?: string;
+  /** A package plugin's installed version. */
+  version?: string;
+};
+//#endregion
+//#region src/references/resolve-reference.d.ts
+type ReferenceStatus = 'found' | 'missing' | 'ambiguous' | 'invalid';
+/** Why an ambiguous name's contributions cannot be put in one order. */
+type AmbiguousCause = 'unordered' | 'cycle' | 'repeat' | 'alias';
+/** Where a contribution's operation came from: its own `merge`, a step's key, or the default `patch`. */
+type OperationSource = 'contribution' | 'step' | 'default';
+/** One layer checked, as the trace reports it. */
+type ReferenceTraceLayer = {
+  tier: ReferenceTier;
+  plugin?: string;
+  skill?: string;
+  /** The file matched, or the folder checked when none matched. */
+  path: string;
+  /** The file that answered, relative to the folder: `<name>.md`, `<name>/README.md`, `<name>.default.md`, or the same with a data extension. */
+  file?: string;
+  /** Its frontmatter as written. */
+  frontmatter?: Record<string, unknown>;
+  operation?: MergeOperation;
+  operationFrom?: OperationSource;
+  /** `used`; `stale`; `shadowed by ...`; `not used (...)`; `not read (...)`; `ambiguous`; or `missing`. */
+  outcome: string;
+  /** A generated `repo` or `user` document: each recorded source with its recorded and installed versions (R9). */
+  sources?: ReferenceTraceSource[];
+  /** A generated `repo` or `user` document: the request it records. */
+  request?: string;
+  /** Set when its `extends` was written but did not build the stack, and why. */
+  extendsOutcome?: string;
+  description?: string;
+  /** A contribution with `extends` and no body: it picks the stack and changes nothing else. */
+  selection?: boolean;
+  /** A contribution with no body, which changes nothing unless it is a `remove`. */
+  empty?: boolean;
+  /** A file filed under an older name of the name (R97): that older name. */
+  alias?: string;
+};
+type ReferenceTraceContribution = {
+  tier: ReferenceTier;
+  plugin?: string;
+  skill?: string;
+  path: string;
+  operation: MergeOperation;
+};
+type ReferenceTraceSection = {
+  /** The heading path, such as `Review > Checklist`. */
+  path: string;
+  /** The contributions that supplied its text, bottom first, each with the operation it applied. */
+  contributions: SectionSource[];
+  /** Set on a section a `remove` dropped: the contribution that dropped it. */
+  removedBy?: string;
+};
+type ReferenceTrace = {
+  /** The plugins and `default` the name builds on, bottom first. */
+  stack: string[];
+  /** What built the stack: the contribution whose `extends` was used, a plugin's own `extends`, or `none`. */
+  builtBy: string;
+  /** The contributions whose text the document holds, bottom first. */
+  contributions: ReferenceTraceContribution[];
+  sections: ReferenceTraceSection[];
+  /** Every layer checked, highest first. */
+  layers: ReferenceTraceLayer[];
+  /** The harnesses detected, whose managed folders and enabled plugins were read. */
+  harnesses: string[];
+  /** When a `remove` turned the whole name off (`reference-removed`): that contribution. */
+  removedBy?: string;
+  /** Each project section found, in path order, delivered or not, and each one in a folder git ignores. */
+  projectSections: ReferenceTraceProjectSection[];
+  /** An older name asked for: the alias followed to the name resolved (R98). */
+  alias?: {
+    name: string;
+    resolvedAs: string;
+  };
+};
+/** A name resolved, with every field: the command prints a subset. A bad name is a status, never thrown. */
+type ResolvedReference = {
+  name: string;
+  status: ReferenceStatus;
+  /** Set when not `found`. */
+  code?: ReferenceStatusCode;
+  /** Why it is not `found`, for a person. */
+  message?: string;
+  content?: string;
+  /** Set when `found`: `markdown`, or the format of the data file that answered whole. */
+  format?: ReferenceFormat;
+  /** The composed frontmatter, key by key with the higher contribution winning, without `merge`, `extends`, `sources`, and `request`. */
+  metadata?: Record<string, unknown>;
+  /** When `found`: what each folder below the root adds after the main document, in path order (R99). */
+  projectSections: ResolvedProjectSection[];
+  /** When `ambiguous`: each `<plugin>/<name>`, and `default` when the skill has one. */
+  options?: string[];
+  cause?: AmbiguousCause;
+  warnings: ReferenceWarning[];
+  trace: ReferenceTrace;
+};
+type ResolveOptions = {
+  /** How a path is shown in a label or a warning — the command collapses the home directory. */
+  display?: (path: string) => string;
+  /** A file read as absent, so `delete --dry-run` can report what answers once it is gone. */
+  without?: string | undefined;
+  /** Read only the layers below this folder, so `where` can report the document below a file it would write. */
+  below?: string | undefined;
+  /** `false` reads no project section, so `check` checks the main document alone (R118). */
+  projectSections?: boolean | undefined;
+};
+type Source = ReferenceLayers | readonly ReferenceLayer[];
+/**
+ * Resolves one name: reads each layer, puts the contributions in one order (the stack under the
+ * user, repo, and managed tiers), and composes them bottom first, each with its operation.
+ */
+declare function resolveReference(input: string | ReferenceName, source: Source, options?: ResolveOptions): ResolvedReference;
+declare function referenceNames(source: Source): string[];
+//#endregion
+//#region src/references/reference-where.d.ts
+/** A file a customization or a selection of the name is written to. A plugin's or a default's is read-only, never one. */
+type ReferenceWhereFile = {
+  /** `repo`, `user`, or the `--in` folder, relative to the root with `/`. */
+  scope: string;
+  /** The file that answers there now, else the `<name>.md` a write creates; relative to the root, except a `user` one. */
+  path: string;
+  /** Who a file there reaches. */
+  reaches: string;
+  /** The contribution above that hides a file there, file there or not (R57, UC2.10). */
+  hiddenBy?: string;
+};
+type ReferenceWhereReport = {
+  name: string;
+  status: ReferenceStatus;
+  files: ReferenceWhereFile[];
+  /** The main document's heading paths, which a section operation can target. */
+  headings: string[];
+  /** The plugins and `default` the stack uses, bottom first: read-only. */
+  used: string[];
+  /** When `ambiguous`: the options a selection written to a file chooses between. */
+  options?: string[];
+  /** Every layer checked, highest first; a plugin's or a default contribution is read-only. */
+  layers: ReferenceTraceLayer[];
+  warnings: ReferenceWarning[];
+};
+type WhereOptions = {
+  /** Absolute; a repo write goes to its `.agents/references/`, and a repo path is shown relative to it. */
+  root: string;
+  /** How a path outside the project is shown, such as with the home directory collapsed to `~`. */
+  display?: ((path: string) => string) | undefined;
+  /** A folder strictly below the root, whose project section file is also given (`in-not-below-root` otherwise). */
+  in?: string | undefined;
+};
+/**
+ * The files a customization of `name` is written to, `repo` and `user` and, with `in`, that folder's
+ * project section, each with who it reaches and what hides it; the main document's heading paths;
+ * and the plugins the stack uses, which are read-only. An `ambiguous` name is an answer, with its
+ * options.
+ */
+declare function whereReference(input: string | ReferenceName, source: ReferenceLayers | readonly ReferenceLayer[], { root, display, in: folder }: WhereOptions): ReferenceWhereReport;
+//#endregion
+export { AssetPlugin as $, referenceLayers as A, ReferenceCode as B, ReferenceLayer as C, ReferenceTier as D, ReferencePlugin as E, ReferenceSourcePlugin as F, ReferenceWarning as G, ReferenceErrorCode as H, ReferenceTraceSource as I, referenceCodes as J, ReferenceWarningCode as K, ProjectFolder as L, userReferencesDir as M, GeneratedRecord as N, SkillDefaults as O, ReferenceSource as P, AssetLayerOptions as Q, ProjectFolderCache as R, PluginOrigin as S, ReferenceLayers as T, ReferenceNoticeCode as U, ReferenceCodeKind as V, ReferenceStatusCode as W, skillName as X, FoundSkill as Y, skillsIn as Z, ResolvedProjectSection as _, AmbiguousCause as a, MergeOperation as b, ReferenceTrace as c, ReferenceTraceSection as d, AssetTier as et, ResolveOptions as f, ReferenceTraceProjectSection as g, resolveReference as h, whereReference as i, repoReferencesDir as j, defaultLayer as k, ReferenceTraceContribution as l, referenceNames as m, ReferenceWhereReport as n, Platform as nt, OperationSource as o, ResolvedReference as p, referenceCodeExit as q, WhereOptions as r, ReferenceStatus as s, ReferenceWhereFile as t, AssetWarning as tt, ReferenceTraceLayer as u, ReferenceName as v, ReferenceLayerOptions as w, SectionSource as x, parseReferenceName as y, ProjectFolders as z };