cyber-agentkit 1.1.0 → 2.0.0

package/dist/index.d.ts

@@ -1,27 +1,97 @@
 import { n as harnessIds, t as HarnessId } from "./harness-id-BgKL-x6C.js";
-import { A as FoundSkill, C as defaultLayer, D as ReferenceCode, E as userReferencesDir, M as skillsIn, N as Platform, O as ReferenceWarning, S as SkillDefaults, T as referenceLayers, _ as ReferenceLayer, a as ReferenceTrace, b as ReferencePlugin, c as ReferenceTraceSection, d as referenceNames, f as resolveReference, g as SectionSource, h as MergeOperation, i as ReferenceStatus, j as skillName, k as ReferenceWarningCode, l as ResolveOptions, m as parseReferenceName, n as ExtendsStep, o as ReferenceTraceContribution, p as ReferenceName, r as OperationSource, s as ReferenceTraceLayer, t as AmbiguousCause, u as ResolvedReference, v as ReferenceLayerOptions, w as projectReferencesDir, x as ReferenceTier, y as ReferenceLayers } from "./resolve-reference-D62VJZc0.js";
-//#region src/references/load-reference.d.ts
-/** `referenceLayers`' options, with the machine's own home directory, platform, and environment by default. */
-type LoadReferenceOptions = Omit<ReferenceLayerOptions, 'home' | 'platform' | 'folder'> & {
-  home?: string | undefined;
-  platform?: Platform | undefined;
+import { A as referenceLayers, B as ReferenceCode, C as ReferenceLayer, D as ReferenceTier, E as ReferencePlugin, F as ReferenceSourcePlugin, G as ReferenceWarning, H as ReferenceErrorCode, I as ReferenceTraceSource, J as referenceCodes, K as ReferenceWarningCode, L as ProjectFolder, M as userReferencesDir, N as GeneratedRecord, O as SkillDefaults, P as ReferenceSource, Q as AssetLayerOptions, R as ProjectFolderCache, S as PluginOrigin, T as ReferenceLayers, U as ReferenceNoticeCode, V as ReferenceCodeKind, W as ReferenceStatusCode, X as skillName, Y as FoundSkill, Z as skillsIn, _ as ResolvedProjectSection, a as AmbiguousCause, b as MergeOperation, c as ReferenceTrace, d as ReferenceTraceSection, et as AssetTier, f as ResolveOptions, g as ReferenceTraceProjectSection, h as resolveReference, i as whereReference, j as repoReferencesDir, k as defaultLayer, l as ReferenceTraceContribution, m as referenceNames, n as ReferenceWhereReport, nt as Platform, o as OperationSource, p as ResolvedReference, q as referenceCodeExit, r as WhereOptions, s as ReferenceStatus, t as ReferenceWhereFile, tt as AssetWarning, u as ReferenceTraceLayer, v as ReferenceName, w as ReferenceLayerOptions, x as SectionSource, y as parseReferenceName, z as ProjectFolders } from "./reference-where-BsBpwLyg.js";
+//#region src/references/reference-stack.d.ts
+/** One `sections` entry of a step: a top-level heading, and the operation it applies with when one is written. */
+type StepSection = {
+  heading: string;
+  merge?: MergeOperation;
 };
 /**
- * Resolves one reference for `root` the way `reference show` does, returning the full record: every
- * field `show` prints with `--metadata` and `--trace`. A name that is not a reference name comes back
- * `invalid`, and one no contribution answers `missing`; neither throws.
+ * One `extends` entry: a plugin or `default`, with the keys to use for it in place of its own. With
+ * `sections`, it contributes only those top-level sections (R52).
  */
-export declare function loadReference(name: string, options: LoadReferenceOptions & {
-  folder?: ReferenceLayerOptions['folder'];
-}): Promise<ResolvedReference>;
+type ExtendsStep = {
+  target: string;
+  merge?: MergeOperation;
+  extends?: ExtendsStep[];
+  sections?: StepSection[];
+};
+//#endregion
+//#region src/assets/asset-name.d.ts
+type AssetFormat = 'markdown' | 'json' | 'yaml' | 'toml' | 'txt';
+//#endregion
+//#region src/assets/resolve-asset.d.ts
+type AssetStatus = 'found' | 'missing' | 'ambiguous' | 'invalid';
+/** One layer checked, as the trace reports it. */
+type AssetTraceLayer = {
+  tier: AssetTier;
+  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>.<ext>`. */
+  file?: string;
+  operation?: 'replace';
+  operationFrom?: 'default' | 'contribution';
+  /** `used`; `shadowed by ...`; `not used (...)`; `not read (...)`; `ambiguous`; or `missing`. */
+  outcome: string;
+  /** A file with nothing in it. */
+  empty?: boolean;
+};
+type AssetTraceContribution = {
+  tier: AssetTier;
+  plugin?: string;
+  skill?: string;
+  path: string;
+  operation: 'replace';
+};
+type AssetTrace = {
+  /** The plugins and `default` the name builds on, bottom first. */
+  stack: string[];
+  /** What decided the stack: `selection`, `qualified name`, or `none`. */
+  builtBy: string;
+  /** The contributions whose text the answer holds, bottom first. */
+  contributions: AssetTraceContribution[];
+  /** Always empty: an asset is never composed. Kept so the trace has the shape a reference trace has. */
+  sections: never[];
+  /** Every layer checked, highest first. */
+  layers: AssetTraceLayer[];
+  /** The harnesses detected, whose managed folders and enabled plugins were read. */
+  harnesses: string[];
+};
+/** A name resolved, with every field: the command prints a subset. A bad name is a status, never thrown. */
+type ResolvedAsset = {
+  name: string;
+  status: AssetStatus;
+  /** Set when not `found`. */
+  code?: 'reference-missing' | 'reference-ambiguous' | 'reference-invalid';
+  /** Why it is not `found`, for a person. */
+  message?: string;
+  /** The file as written. */
+  content?: string;
+  /** Set when `found`: `markdown`, or the format of the data file that answered. */
+  format?: AssetFormat;
+  /** Always empty: an asset has no frontmatter that composes. */
+  metadata?: Record<string, unknown>;
+  /** When `ambiguous`: each `<plugin>/<name>`, and `default` when the skill has one. */
+  options?: string[];
+  cause?: 'unordered';
+  warnings: AssetWarning[];
+  trace: AssetTrace;
+};
 //#endregion
 //#region src/assets/load-asset.d.ts
+/** `assetLayers`' options, with the machine's own home directory, platform, and environment by default. */
+type LoadAssetOptions = Omit<AssetLayerOptions, 'home' | 'platform'> & {
+  home?: string | undefined;
+  platform?: Platform | undefined;
+};
 /**
- * Resolves one asset by name the way `asset load` does: the reference engine, reading `assets/` where
- * it reads `references/`. A data file answers whole from the highest tier holding the name; the skill's
- * own `assets/<name>.<ext>` (`defaultSkill`) is the lowest.
+ * Resolves one asset by name the way `asset load` does, reading `assets/` folders through the tiers.
+ * A data file answers whole from the highest tier holding the name; the skill's own
+ * `assets/<name>.<ext>` (`defaultSkill`) is the lowest.
  */
-export declare function loadAsset(name: string, options: LoadReferenceOptions): Promise<ResolvedReference>;
+export declare function loadAsset(name: string, options: LoadAssetOptions): Promise<ResolvedAsset>;
 //#endregion
 //#region src/harness/harness-environment.d.ts
 /**
@@ -426,6 +496,111 @@ interface PluginStorage {
  */
 export declare function pluginStorage(harness: HarnessId, environment?: HarnessEnvironment): PluginStorage;
 //#endregion
+//#region src/prose-update/split-sentences.d.ts
+type SentenceKind = 'text' | 'heading' | 'item' | 'row' | 'fence' | 'quote';
+/** The unit prose-update compares: see K4 in the prose-update spec. */
+type Sentence = {
+  text: string;
+  kind: SentenceKind;
+  /** What separated this sentence from the one before it: nothing, a space, a newline, or a blank line. */
+  gap: '' | ' ' | '\n' | '\n\n';
+};
+//#endregion
+//#region src/prose-update/merge.d.ts
+/** A place where the owner and the offered wording each changed the same base sentences differently. */
+type Collision = {
+  base: Sentence[];
+  found: Sentence[];
+  offered: Sentence[];
+};
+//#endregion
+//#region src/prose-update/classify.d.ts
+type Outcome = 'up-to-date' | 'update' | 'conflict' | 'owners' | 'undetermined';
+type Reason = 'no-history' | 'empty-section' | 'tied-base' | 'no-base';
+/** The retired wording a found text descends from: its place in the history (0 is the newest) and its date. */
+type BaseRef = {
+  index: number;
+  date?: string | undefined;
+};
+type PartResult = {
+  path: string[];
+  key: string;
+  outcome: Outcome;
+  reason?: Reason;
+  /** Set with `tied-base`: the places in the history of the wordings that tied. */
+  tied?: number[];
+  base?: BaseRef;
+  /** Sentences the found part shares with the base part (K10), and the base part's sentence count. */
+  shared?: number;
+  baseSentences?: number;
+  revision?: 'append' | 'rewrite';
+  /** The part's text: as found for `up-to-date` and `owners`, merged for `update` (empty when the part is removed). */
+  text?: string;
+  collisions?: Collision[];
+};
+type Classification = {
+  outcome: Outcome;
+  reason?: Reason;
+  base?: BaseRef;
+  parts: PartResult[];
+  /** The found text for every outcome but `update` and `conflict`; the merged text otherwise. */
+  text: string;
+};
+type ClassifyInput = {
+  found: string;
+  offered: string;
+  /** A history text (parsed by `parseHistory`), or retired wordings, newest first. */
+  history: string | readonly string[];
+};
+/** The offered wording is empty, so nothing can be classified (R33). */
+export declare class ProseUpdateError extends Error {
+  readonly code: 'empty-offered';
+  constructor(code: 'empty-offered', message: string);
+}
+/** Classifies each part of the found text against the offered wording and the history, and merges where it can. */
+export declare function classify(input: ClassifyInput): Classification;
+//#endregion
+//#region src/prose-update/history.d.ts
+type RetiredWording = {
+  wording: string;
+  date: string;
+  reason: string;
+};
+/** An entry that did not parse: its place among the `Superseded` headings (from 0), its line (from 1), and its heading. */
+type InvalidEntry = {
+  position: number;
+  line: number;
+  heading: string;
+};
+type ParsedHistory = {
+  entries: RetiredWording[];
+  invalid: InvalidEntry[];
+};
+/**
+ * Reads the retired wordings of a history text, newest first. Each entry is a `## Superseded <date> — <reason>`
+ * heading followed by the wording in a fence. An entry that does not parse is returned in `invalid`.
+ */
+export declare function parseHistory(text: string): ParsedHistory;
+/**
+ * Returns the history text with the outgoing wording added as its newest entry and every other byte unchanged.
+ * The wording equal to the newest retired one changes nothing.
+ */
+export declare function retire(history: string, wording: string, date: string, reason: string): string;
+//#endregion
+//#region src/references/load-reference.d.ts
+/** `referenceLayers`' options, with the machine's own home directory, platform, and environment by default. */
+type LoadReferenceOptions = Omit<ReferenceLayerOptions, 'home' | 'platform'> & {
+  home?: string | undefined;
+  platform?: Platform | undefined;
+};
+/**
+ * Resolves one reference for the root the way `reference load` does, returning the full record: every
+ * field `load` prints with `--metadata` and `--trace`. A name that is not a reference name comes back
+ * `invalid`, and one no contribution answers `missing`; neither throws. An empty name throws
+ * `ReferenceFailure` with `name-missing`, and a `root` that does not exist with `root-missing`.
+ */
+export declare function loadReference(name: string, options: LoadReferenceOptions): Promise<ResolvedReference>;
+//#endregion
 //#region src/references/reference-catalog.d.ts
 /** One row per name. */
 type ReferenceListRow = {
@@ -433,9 +608,12 @@ type ReferenceListRow = {
   name: string;
   description: string;
   status: ReferenceStatus;
+  /** Set when not `found`. */
+  code?: ReferenceStatusCode;
   /** When `ambiguous`: each `<plugin>/<name>`, and each skill's default as `default of <skill>`. */
   options?: string[];
 };
+type ReferenceListRowKind = 'selection' | 'generated' | 'project-section';
 /** One row per name per layer holding it, with the outcome that contribution gets. */
 type ReferenceListLayerRow = {
   name: string;
@@ -445,8 +623,10 @@ type ReferenceListLayerRow = {
   path: string;
   description: string;
   outcome: string;
-  /** A contribution with `extends` and no body. */
-  selection?: boolean;
+  /** What the row is, when it is one: a contribution with `extends` and no body, a generated document, or a project section. */
+  kind?: ReferenceListRowKind;
+  /** A project section's folder, relative to the root. */
+  folder?: string;
   /** A skill's default: the `default` step reaches it when this skill loads the name. */
   reachedBy?: string;
 };
@@ -479,6 +659,8 @@ type SearchMatch = {
   skill?: string;
   /** A match found as this skill loads the name, its default joined. */
   loadedBy?: string;
+  /** A match in a project section: its folder, relative to the root. */
+  folder?: string;
 };
 type ReferenceSearch = {
   matches: SearchMatch[];
@@ -486,8 +668,8 @@ type ReferenceSearch = {
   defaults?: string;
 };
 /**
- * Every name resolves the way `show` would, and each skill's default as its skill loads it; a name
- * no extends orders is searched once per plugin, as the qualified name `show` would need, and a name
+ * Every name resolves the way `load` would, and each skill's default as its skill loads it; a name
+ * no extends orders is searched once per plugin, as the qualified name `load` would need, and a name
  * a `remove` turned off is left out.
  */
 export declare function searchReferences(query: string, source: Source$2, options?: ResolveOptions): ReferenceSearch;
@@ -495,6 +677,14 @@ export declare function searchReferences(query: string, source: Source$2, option
 //#region src/references/reference-interface.d.ts
 /** `one`: the implementation is named `<id>`. `many`: each is named `<id>.<key>`. */
 type InterfaceCardinality = 'one' | 'many';
+/** One section an implementation holds, as the interface lists it (R63, C7). Heading text is API. */
+type InterfaceSection = {
+  heading: string;
+  /** A required section left out or marked `**Unsupported.**` fails the `required` check (R64). */
+  required: boolean;
+  /** One line saying what it holds: an implementation's stub states it (R28). It is never checked. */
+  holds?: string;
+};
 /** The machine-readable part of an interface document, read from its `interface:` frontmatter. */
 type ReferenceInterface = {
   id: string;
@@ -502,15 +692,16 @@ type ReferenceInterface = {
   version: number;
   /** The versions the owner's consumers accept; `[version]` when the document names none. */
   versions: number[];
-  /** The implementation's top-level sections, in order. Every one is optional. Heading text is API. */
-  sections: string[];
+  /** The implementation's top-level sections, in order. */
+  sections: InterfaceSection[];
 };
 /** One `implements:` value, `<id>@<version>`. */
 type ImplementsEntry = {
   id: string;
   version: number;
 };
-type InterfaceCheck = 'interface found' | 'version' | 'name' | 'order' | 'interface' | 'compose';
+/** The checks `check` runs, each named in kebab-case (UC6). */
+type InterfaceCheck = 'interface-found' | 'version' | 'name' | 'order' | 'required' | 'interface' | 'compose';
 type InterfaceCheckFailure = {
   check: InterfaceCheck;
   /** The interface id the failure is about, when the document names one. */
@@ -522,7 +713,7 @@ type InterfaceCheckFailure = {
 type ReferenceCheckKind = 'interface' | 'implementation' | 'none';
 /** A failed check, named by the check; a name not `found` fails with its status code. */
 type ReferenceCheckFailure = {
-  check: InterfaceCheck | ReferenceCode;
+  check: InterfaceCheck | ReferenceStatusCode;
   /** The interface id the failure is about, when the document names one. */
   interface?: string;
   message: string;
@@ -530,35 +721,229 @@ type ReferenceCheckFailure = {
 type ReferenceCheckEntry = {
   name: string;
   kind: ReferenceCheckKind;
-  /** `passed` and `failed` are about the composed document; the others mean none was composed. */
+  /**
+   * `passed` and `failed` are about the composed document; the others mean none was composed. A name
+   * a `remove` turned off is `missing` with no failures: it is off on purpose (R117).
+   */
   status: 'passed' | 'failed' | 'missing' | 'ambiguous' | 'invalid';
+  /** Empty when the entry passes. */
   failures: ReferenceCheckFailure[];
-  /** For an implementation: the listed sections it marks `**Unsupported.**` or leaves out. */
+  /** For an implementation: the optional listed sections it marks `**Unsupported.**` or leaves out. */
   unsupported: string[];
+  /**
+   * What is passed on and never fails a check: a warning composing raised that depends on what is
+   * installed or chosen (UC6.8), every warning a project section raised (R118), an interface's older
+   * id (R96), a moved base (R86), a hidden file (R112).
+   */
+  warnings: ReferenceWarning[];
   /** Checked as this skill loads the name, its default joined. */
   loadedBy?: string;
 };
 type CheckOptions = ResolveOptions & {
-  /** The references to check; every interface document and implementation found when omitted. */
+  /** The references to check; every name found when omitted. */
   names?: readonly string[] | undefined;
 };
 type Source$1 = ReferenceLayers | readonly ReferenceLayer[];
 /**
- * Checks each named reference, or, with no names, every interface document and implementation found.
- * A name several plugins hold is also checked as each `<plugin>/<name>`, so each author sees their own
- * result, and each skill's default as its skill loads it.
+ * Checks each named reference, or, with no names, every name found, reporting every warning `load`
+ * raises for each (R116). A name several plugins hold is also checked as each `<plugin>/<name>`, so
+ * each author sees their own result, and each skill's default as its skill loads it. Beside what
+ * `load` raises, a hidden `repo`, `user`, or project-section file (J2, R112) and a plugin's or
+ * default's file whose base moved (R86) are passed on. A warning never fails a check.
  */
 export declare function checkReferences(source: Source$1, options?: CheckOptions): ReferenceCheckEntry[];
 //#endregion
+//#region src/references/reference-write-target.d.ts
+/**
+ * Where a write lands: the repo or user tier, a folder's project section, or a plugin's or a skill's
+ * source folder in the repository.
+ */
+type WriteScope = 'repo' | 'user' | 'project' | 'plugin' | 'default';
+//#endregion
+//#region src/references/reference-base.d.ts
+/** What the generator reads for a target (R84): the interface's stub when one is named, then the main document. */
+type GeneratorBase = {
+  /** The stub, then the main document built for the target; empty when neither is there. */
+  content: string;
+  /** For a folder target: the project sections of the folders above it, then the package plugins' for its own, in path order. */
+  projectSections: ResolvedProjectSection[];
+  /** The interface's stub, when one is named. */
+  stub?: string;
+  /** The main document built for the target, which a request records the sources of. */
+  resolved: ResolvedReference;
+};
+//#endregion
+//#region src/references/reference-write.d.ts
+type CreateResult = {
+  name: string;
+  scope: WriteScope;
+  path: string;
+  /** A project section's folder, relative to the root. */
+  folder?: string;
+  content: string;
+  dryRun: boolean;
+  /** Things to know that are not faults, such as a missing `description`. */
+  hints: string[];
+  /** Faults that did not stop the write, such as a contribution above that hides the file (R26). */
+  warnings: ReferenceWarning[];
+  /** The name resolved again after the write, when the file is a layer the stack reads or a project section. */
+  after?: ResolvedReference;
+};
+type DeleteResult = {
+  name: string;
+  scope: WriteScope;
+  /** The file deleted, or the one looked for when there was none. */
+  path: string;
+  /** A project section's folder, relative to the root. */
+  folder?: string;
+  /** The metadata file (K31) that went with a non-Markdown file (R95). */
+  metadataFile?: string;
+  dryRun: boolean;
+  /** The file held a selection (`extends`), which went with it. */
+  selection?: string[];
+  /** Set on a no-op: no file there to delete. */
+  code?: 'no-file';
+  /** What the notice says, for a person. */
+  message?: string;
+  /** What answers the name once the file is gone. */
+  after: ResolvedReference;
+};
+//#endregion
+//#region src/references/write-reference.d.ts
+/** Where a write goes; a folder is relative to `cwd`. Pass at most one of `scope`, `in`, `pluginFolder`, and `default`. */
+type PlaceOptions = {
+  /** `repo` (default) or `user`. */
+  scope?: string | undefined;
+  /** A folder strictly below the root, which must exist and not be git-ignored: its project section. */
+  in?: string | undefined;
+  /** A plugin's source folder in the repository: its `references/<name>.md`. */
+  pluginFolder?: string | undefined;
+  /** A skill's source folder in the repository: its `references/<name>.default.md`. It also joins as the `default` tier. */
+  default?: string | undefined;
+  /** Report what would be written or deleted, and change nothing. */
+  dryRun?: boolean | undefined;
+};
+type CreateReferenceOptions = LoadReferenceOptions & PlaceOptions & {
+  /** `replace`, `patch` (default in the `repo` and `user` tiers), `combine`, or `remove`. */
+  merge?: string | undefined;
+  /** A file whose text is written as it is, frontmatter included. */
+  template?: string | undefined;
+  /** An interface id: its sections are written as `##` headings, each stubbed `**Unsupported.**`. */
+  implements?: string | undefined;
+};
+type DeleteReferenceOptions = LoadReferenceOptions & PlaceOptions;
+/**
+ * Starts a contribution the way `reference create` does and returns its record: the path, the
+ * content, its warnings (such as `reference-hidden` for a file a contribution above hides, which is
+ * written all the same), and the name resolved after the write. A refused write throws
+ * `ReferenceError` with its code, marked `usage` for a wrong call.
+ */
+export declare function createReference(name: string, options: CreateReferenceOptions): Promise<CreateResult>;
+/**
+ * Deletes the file answering a name at one place the way `reference delete` does, with a non-Markdown
+ * file's metadata file, and returns what answers the name afterwards. With no file there it is a
+ * no-op whose record carries the `no-file` code. A refused delete throws `ReferenceError`.
+ */
+export declare function deleteReference(name: string, options: DeleteReferenceOptions): Promise<DeleteResult>;
+//#endregion
+//#region src/references/reference-customize.d.ts
+/**
+ * What `customize` did: printed the generator's input (`base`), wrote picks (`selection`), wrote a
+ * generated body (`generated`), or removed the picks (`cleared`).
+ */
+type CustomizeAction = 'base' | 'selection' | 'generated' | 'cleared';
+type CustomizeResult = {
+  name: string;
+  scope: WriteScope;
+  action: CustomizeAction;
+  /** The file written, removed, or that would be: the Markdown file, a data file, or a metadata file holding picks. */
+  path: string;
+  /** A project section's folder, relative to the root. */
+  folder?: string;
+  /** The text written to `path`; none when the file was deleted. */
+  content?: string;
+  /** A non-Markdown name's metadata file (K31), which holds the generated record (R92). */
+  metadataFile?: string;
+  metadataContent?: string;
+  /** The picks written, as `extends` holds them. */
+  extends?: unknown[];
+  /** `--extends none` left the file with nothing in it, so it was deleted. */
+  deleted?: boolean;
+  /** Set on a no-op: `--extends none` with no selection there. */
+  code?: 'no-selection';
+  /** What the notice says, for a person. */
+  message?: string;
+  dryRun: boolean;
+  /** Things to know that are not faults, such as a generated body written against the old stack (R83). */
+  hints: string[];
+  /** Faults that did not stop the write: a contribution above that hides it (R26), or a managed `extends` deciding the stack (R109). */
+  warnings: ReferenceWarning[];
+  /** `base`: what the generator reads for the target. */
+  base?: GeneratorBase;
+  /** The name resolved again after the write. */
+  after?: ResolvedReference;
+};
+type CustomizeReferenceOptions = LoadReferenceOptions & Omit<PlaceOptions, 'pluginFolder'> & {
+  /** The picks, bottom first: each `<plugin>`, `<plugin>:<merge>`, or `default`; `['none']` removes them. */
+  extends?: readonly string[] | undefined;
+  /** A YAML file holding the whole `extends` list. */
+  extendsFile?: string | undefined;
+  /** The file holding the customizer's request; pass it with `body`. */
+  request?: string | undefined;
+  /** The file holding the body to write; pass it with `request`. */
+  body?: string | undefined;
+  /** How a generated body applies over what is below: `patch` (default), `combine`, `replace`, or `remove`. */
+  merge?: string | undefined;
+  /** An interface id: the body is a whole implementation of it. */
+  implements?: string | undefined;
+  /** Return the generator's input (R84) and write nothing. */
+  base?: boolean | undefined;
+};
+/**
+ * Customizes a name the way `reference customize` does and returns its record: what was written,
+ * its warnings (such as `reference-hidden`), and the name resolved after; with `base`, the
+ * generator's input. A refused customization throws `ReferenceError` with its code, marked `usage`
+ * for a wrong call.
+ */
+export declare function customizeReference(name: string, options: CustomizeReferenceOptions): Promise<CustomizeResult>;
+//#endregion
+//#region src/references/reference-error.d.ts
+type ReferenceErrorOptions = {
+  /** Fields an agent can act on, such as the path refused. Each value a scalar or a list of scalars. */
+  details?: Record<string, string | number | boolean | null | readonly (string | number | boolean | null)[]> | undefined;
+  /** What to do about it, such as the command that fixes it. */
+  help?: string | readonly string[] | undefined;
+};
+/**
+ * A request a reference function cannot complete, or one called wrongly, thrown by a library
+ * function and by a write (R48). The `code` is stable and in `referenceCodes`; `usage` marks a wrong
+ * invocation, which a command exits 2 on, rather than a refusal, which it exits 1 on. A name that is
+ * not `found` is a status in its record, never this error.
+ *
+ * The package exports it as `ReferenceError` (C9); inside the source it keeps this name, so no module
+ * shadows the global `ReferenceError`.
+ */
+declare class ReferenceFailure extends Error {
+  readonly name = "ReferenceError";
+  readonly code: ReferenceCode;
+  readonly usage: boolean;
+  readonly details: NonNullable<ReferenceErrorOptions['details']>;
+  readonly help: string[];
+  constructor(code: ReferenceCode, message: string, { details, help }?: ReferenceErrorOptions);
+}
+//#endregion
 //#region src/references/reference-implementations.d.ts
 type ReferenceImplementation = {
-  /** What a consumer loads: the name as it resolved, `<plugin>/<name>` when no extends orders the plugins holding it. */
+  /**
+   * What a consumer loads: a plugin's implementation by its qualified name, `<plugin>/<name>`; a
+   * `repo` or `user` implementation of a `many` interface by its bare name (R35).
+   */
   pin: string;
   description: string;
-  /** The listed sections it marks `**Unsupported.**` or leaves out, in the interface's order. */
+  /** The optional listed sections it marks `**Unsupported.**` or leaves out, in the interface's order. */
   unsupported: string[];
   name: string;
-  /** The tier of the highest contribution whose text it holds. */
+  /** `plugin`, or the `repo` or `user` tier of a bare-name implementation. */
   tier: ReferenceTier;
   version: number;
 };
@@ -582,45 +967,16 @@ type ImplementationsOptions = ResolveOptions & {
 type Source = ReferenceLayers | readonly ReferenceLayer[];
 /**
  * The implementations of interface `id` a consumer may load, each checked as `check` would on its
- * composed document, and every candidate left out with why. A candidate is a name in the interface's
- * namespace (`<id>` or `<id>.<key>`) or a reference that declares `implements: <id>@<n>`. A skill's
- * default is never listed: it has no qualified name to pin. An unknown interface throws.
+ * composed document, and every candidate left out with why (R35). A candidate is a name in the
+ * interface's namespace (`<id>` or `<id>.<key>`) or a reference that declares `implements: <id>@<n>`:
+ * a plugin's, pinned by its qualified name, or, for a `many` interface, a `repo` or `user` one,
+ * pinned by its bare name. When a `repo` or `user` implementation answers the bare name, a plugin's
+ * of that name is left out (C1, J3), since loading the bare name returns the other. Plugins holding
+ * a name no `extends` orders are all left out until a customizer picks one (R87). A skill's default
+ * is never listed: it has no qualified name to pin. An unknown interface throws.
  */
 export declare function referenceImplementations(id: string, source: Source, options?: ImplementationsOptions): ReferenceImplementations;
 //#endregion
-//#region src/references/reference-where.d.ts
-/** A file a customization or a selection of the name is written to. */
-type ReferenceWherePlace = {
-  scope: 'project' | 'user';
-  /** The project path is relative to the root; the user path is shown as the command displays it. */
-  path: string;
-  reaches: string;
-  /** `used`, `shadowed by ...`, or `not used (...)` when the file exists; `empty` when it does not. */
-  status: string;
-  /** The heading paths of the document below it, which a section operation can target. */
-  sections: string[];
-};
-type ReferenceWhereReport = {
-  name: string;
-  status: ReferenceStatus;
-  places: ReferenceWherePlace[];
-  /** When `ambiguous`: the options a selection written to a place 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 project write goes to its `.agents/references/`, and a project 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;
-  /** An assets call: the project write goes to `.agents/assets/`. */
-  assets?: boolean | undefined;
-};
-/** The project and user files a customization of `name` is written to, with the document below each. */
-export declare function whereReference(input: string | ReferenceName, source: ReferenceLayers | readonly ReferenceLayer[], { root, display, assets }: WhereOptions): ReferenceWhereReport;
-//#endregion
 //#region src/skills/harness-skill-folders.d.ts
 /**
  * The harnesses whose skill folders are verified: project, user, machine-wide admin, and plugin
@@ -734,4 +1090,4 @@ interface SkillsDirectories {
  */
 export declare function skillsDirectories(harness: HarnessId): SkillsDirectories | undefined;
 //#endregion
-export { type AmbiguousCause, type CheckOptions, type CheckPluginDependenciesOptions, type CheckedDependency, type DependencyState, type DetectHarnessOptions, type EnabledPluginSource, type EnabledPluginsOptions, type EnabledPluginsResult, type ExcludedImplementation, type ExtendsStep, type FoundSkill, type HarnessDetectionResult, type HarnessEnvironment, type HarnessEvidence, type HarnessId, type HeadlessCommand, type HeadlessCommandOptions, type HeadlessExitCode, type HeadlessInvocation, type HeadlessMode, type HeadlessOutputFormat, type HeadlessPermission, type HeadlessTranscript, type HeadlessUnavailable, type HeadlessUsage, type ImplementationsOptions, type ImplementsEntry, type InstalledPlugin, type InstalledPluginSource, type InstalledPluginsResult, type InterfaceCardinality, type InterfaceCheck, type InterfaceCheckFailure, type ListOptions, type LoadReferenceOptions, type ManagedPolicyKind, type ManagedPolicyLocation, type ManagedPolicyOptions, type MatchKind, type MergeOperation, type OperationSource, type Platform, type PluginDependenciesRead, type PluginDependency, type PluginDependencyCheck, type PluginEnablement, type PluginScope, type PluginSkill, type PluginStorage, type PluginStorageKind, type PluginStorageLocation, type ReferenceCheckEntry, type ReferenceCheckFailure, type ReferenceCheckKind, type ReferenceCode, type ReferenceImplementation, type ReferenceImplementations, type ReferenceInterface, type ReferenceLayer, type ReferenceLayerOptions, type ReferenceLayers, type ReferenceListLayerRow, type ReferenceListRow, type ReferenceListing, type ReferenceName, type ReferencePlugin, type ReferenceSearch, type ReferenceStatus, type ReferenceTier, type ReferenceTrace, type ReferenceTraceContribution, type ReferenceTraceLayer, type ReferenceTraceSection, type ReferenceWarning, type ReferenceWarningCode, type ReferenceWherePlace, type ReferenceWhereReport, type ResolveOptions, type ResolvedReference, type SearchMatch, type SectionSource, type SkillDefaults, type SkillFolderOptions, type SkillInvocation, type SkillsDirectories, type WhereOptions, defaultLayer, harnessIds, parseReferenceName, projectReferencesDir, referenceLayers, referenceNames, resolveReference, skillName, skillsIn, userReferencesDir };
+export { type AmbiguousCause, type BaseRef, type CheckOptions, type CheckPluginDependenciesOptions, type CheckedDependency, type Classification, type ClassifyInput, type Collision, type CreateReferenceOptions, type CreateResult, type CustomizeAction, type CustomizeReferenceOptions, type CustomizeResult, type DeleteReferenceOptions, type DeleteResult, type DependencyState, type DetectHarnessOptions, type EnabledPluginSource, type EnabledPluginsOptions, type EnabledPluginsResult, type ExcludedImplementation, type ExtendsStep, type FoundSkill, type GeneratedRecord, type GeneratorBase, type HarnessDetectionResult, type HarnessEnvironment, type HarnessEvidence, type HarnessId, type HeadlessCommand, type HeadlessCommandOptions, type HeadlessExitCode, type HeadlessInvocation, type HeadlessMode, type HeadlessOutputFormat, type HeadlessPermission, type HeadlessTranscript, type HeadlessUnavailable, type HeadlessUsage, type ImplementationsOptions, type ImplementsEntry, type InstalledPlugin, type InstalledPluginSource, type InstalledPluginsResult, type InterfaceCardinality, type InterfaceCheck, type InterfaceCheckFailure, type InterfaceSection, type InvalidEntry, type ListOptions, type LoadAssetOptions, type LoadReferenceOptions, type ManagedPolicyKind, type ManagedPolicyLocation, type ManagedPolicyOptions, type MatchKind, type MergeOperation, type OperationSource, type Outcome, type ParsedHistory, type PartResult, type Platform, type PluginDependenciesRead, type PluginDependency, type PluginDependencyCheck, type PluginEnablement, type PluginOrigin, type PluginScope, type PluginSkill, type PluginStorage, type PluginStorageKind, type PluginStorageLocation, type ProjectFolder, type ProjectFolderCache, type ProjectFolders, type Reason, type ReferenceCheckEntry, type ReferenceCheckFailure, type ReferenceCheckKind, type ReferenceCode, type ReferenceCodeKind, ReferenceFailure as ReferenceError, type ReferenceErrorCode, type ReferenceErrorOptions, type ReferenceImplementation, type ReferenceImplementations, type ReferenceInterface, type ReferenceLayer, type ReferenceLayerOptions, type ReferenceLayers, type ReferenceListLayerRow, type ReferenceListRow, type ReferenceListRowKind, type ReferenceListing, type ReferenceName, type ReferenceNoticeCode, type ReferencePlugin, type ReferenceSearch, type ReferenceSource, type ReferenceSourcePlugin, type ReferenceStatus, type ReferenceStatusCode, type ReferenceTier, type ReferenceTrace, type ReferenceTraceContribution, type ReferenceTraceLayer, type ReferenceTraceProjectSection, type ReferenceTraceSection, type ReferenceTraceSource, type ReferenceWarning, type ReferenceWarningCode, type ReferenceWhereFile, type ReferenceWhereReport, type ResolveOptions, type ResolvedAsset, type ResolvedProjectSection, type ResolvedReference, type RetiredWording, type SearchMatch, type SectionSource, type SkillDefaults, type SkillFolderOptions, type SkillInvocation, type SkillsDirectories, type WhereOptions, type WriteScope, defaultLayer, harnessIds, parseReferenceName, referenceCodeExit, referenceCodes, referenceLayers, referenceNames, repoReferencesDir, resolveReference, skillName, skillsIn, userReferencesDir, whereReference };