@dikolab/kbdb 0.6.3 → 0.6.5

package/dist/src/shared/cli/functions/learn-markdown-document.function.d.ts

@@ -0,0 +1,22 @@
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Attempts to ingest `content` as a multi-section markdown
+ * document, splitting on ATX headings and grouping the resulting
+ * sections under one shared document via `client.groupSections()`.
+ *
+ * Returns `undefined` when splitting does not apply -- fewer than
+ * two sections, or none carry a heading title -- signalling that
+ * the caller should fall back to single-section ingestion.
+ *
+ * @param client - learn client used to add and group sections
+ * @param options - parsed CLI options (tags, replace, description)
+ * @param path - source file path, or `'-'` for stdin
+ * @param content - raw markdown document text
+ * @param sourcePath - absolute file path for supersession, or
+ *   `undefined` for stdin input
+ * @returns one `LearnResult` per section, or `undefined` when the
+ *   document does not warrant splitting
+ */
+export declare function learnMarkdownDocument(client: LearnClient, options: CliOptions, path: string, content: string, sourcePath?: string): Promise<LearnResult[] | undefined>;

package/dist/src/shared/cli/functions/learn-structured-document.function.d.ts

@@ -0,0 +1,10 @@
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+import type { SplitResult } from '../../content-splitter/index.ts';
+/**
+ * Stores each section of a split result as a separate
+ * knowledge-base section with parent resolution, then
+ * groups them under one document.
+ */
+export declare function learnStructuredDocument(client: LearnClient, options: CliOptions, path: string, splitResult: SplitResult, sourcePath?: string): Promise<LearnResult[]>;

package/dist/src/shared/cli/functions/learn-target-content.function.d.ts

@@ -0,0 +1,12 @@
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { CliOptions } from '../typings/cli-options.interface.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Ingests one already-read target as either a single section
+ * or, for eligible structured content (Markdown, HTML, TOML),
+ * a set of sections grouped under one document.
+ *
+ * Splitting is attempted when `options.title` is not set and
+ * the content produces 2+ sections with at least one heading.
+ */
+export declare function learnTargetContent(client: LearnClient, options: CliOptions, path: string, content: string, sourcePath?: string, level?: number): Promise<LearnResult[]>;

package/dist/src/shared/cli/functions/map-add-section-result.function.d.ts

@@ -0,0 +1,12 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
+import type { LearnResult } from '../typings/learn-result.model.ts';
+/**
+ * Maps an `AddSectionResult` returned by the worker daemon to the
+ * `LearnResult` record consumed by the `learn` CLI command.
+ *
+ * @param result - raw result from `client.addSection()`
+ * @param path - source file path, or `'-'` for stdin
+ * @param size - UTF-8 character count of the ingested content
+ * @param sectionType - semantic type used for ingestion
+ */
+export declare function mapAddSectionResult(result: AddSectionResult, path: string, size: number, sectionType: string): LearnResult;

package/dist/src/shared/cli/functions/run-agent-list.function.d.ts

@@ -28,18 +28,22 @@ export interface AgentListClient {
     listDocumentsByType(docType: string): Promise<DocumentSummary[]>;
 }
 /**
- * Lists all agents stored in the knowledge base.
+ * Lists agents stored in the knowledge base.
  *
  * Retrieves all documents with `doc_type: 'agent'` and returns a
- * summary list. The `skillCount` for each agent is
- * `Math.max(0, sections.length - 1)` because the first section
- * always holds the agent's metadata JSON rather than a skill
- * reference.
+ * JSON envelope of matching agent names. When `options.args` is
+ * non-empty, the positional arguments are joined with a space
+ * and used as a case-insensitive substring filter against each
+ * agent's name. An empty query returns every agent. Filtering by
+ * description is not available here because it would require an
+ * extra `readSections` call per agent; use the MCP `agent-list`
+ * tool for description filtering.
  *
  * @param client - agent list client to delegate retrieval to
- * @param _options - parsed CLI options (unused; reserved for future
- *   filtering flags)
- * @returns a `CommandResult` with serialised agent summary list
+ * @param options - parsed CLI options; positional `args` build
+ *   the filter query
+ * @returns a `CommandResult` with a JSON envelope
+ *   (`{ items, total, offset }`) of matching agent names
  */
-export declare function runAgentList(client: AgentListClient, _options: CliOptions): Promise<CommandResult>;
+export declare function runAgentList(client: AgentListClient, options: CliOptions): Promise<CommandResult>;
 export {};

package/dist/src/shared/cli/functions/run-learn.function.d.ts

@@ -1,62 +1,9 @@
 import type { CliOptions } from '../typings/cli-options.interface.ts';
 import type { LearnResult } from '../typings/learn-result.model.ts';
-/** Enriched add-section result returned by the daemon. */
-interface AddSectionResult {
-    /** List of knowledge-base identifiers assigned. */
-    readonly items: string[];
-    /** Number of items in the result set. */
-    readonly total: number;
-    /** Offset into the result set (always 0 for learn). */
-    readonly offset: number;
-    /**
-     * Kbid of the section superseded via `--replace`,
-     * or `null` / `undefined` when none.
-     */
-    readonly superseded?: string | null;
-    /**
-     * Advisory warning strings (e.g. `"heading_missing"`).
-     * May be absent from older daemon versions.
-     */
-    readonly warnings?: string[];
-    /**
-     * Near-duplicate sections with similarity >= 0.85.
-     * May be absent from older daemon versions.
-     */
-    readonly near_duplicates?: {
-        readonly kbid: string;
-        readonly similarity: number;
-    }[];
-}
-/**
- * Minimal client interface required by `runLearn`.
- *
- * Decouples the CLI function from the concrete `WorkerClient`
- * implementation, making it straightforward to test with mocks.
- */
-export interface LearnClient {
-    /**
-     * Ingests a content section into the knowledge base.
-     *
-     * @param params - section metadata and raw text content
-     * @returns enriched result containing the new kbid plus
-     *   optional supersession, warnings, and near-duplicate info
-     */
-    addSection(params: {
-        sectionType: string;
-        content: string;
-        title?: string;
-        description?: string;
-        docid?: string;
-        tags?: string[];
-        replace?: boolean;
-        sourcePath?: string;
-        level?: number;
-    }): Promise<AddSectionResult>;
-}
-/** Injectable I/O for testing without real stdin. */
-export interface LearnIO {
-    readStdin: () => Promise<string>;
-}
+import type { LearnClient } from '../typings/learn-client.interface.ts';
+import type { LearnIO } from '../typings/learn-io.interface.ts';
+export type { LearnClient } from '../typings/learn-client.interface.ts';
+export type { LearnIO } from '../typings/learn-io.interface.ts';
 /**
  * Ingests one or more files or directories listed in `options.args`
  * into the knowledge base via the provided client.
@@ -72,11 +19,15 @@ export interface LearnIO {
  * directory to derive a level from, so it is sent unset unless
  * `options.level` is explicit.
  *
+ * `.md` files and stdin input are split into multiple sections on
+ * ATX headings and grouped under one document when the content has
+ * 2+ headings and `options.title` is not set explicitly -- see
+ * `learnTargetContent()` for the exact rule.
+ *
  * @param client - learn client to delegate ingestion to
  * @param options - parsed CLI options whose `args` list targets to
  *   ingest
  * @param io - injectable I/O (defaults to reading process.stdin)
- * @returns one `LearnResult` per file successfully ingested
+ * @returns one `LearnResult` per section successfully ingested
  */
 export declare function runLearn(client: LearnClient, options: CliOptions, io?: LearnIO): Promise<LearnResult[]>;
-export {};

package/dist/src/shared/cli/functions/run-skill-list.function.d.ts

@@ -29,15 +29,19 @@ export interface SkillListClient {
     listByType(sectionType: string): Promise<SkillRecord[]>;
 }
 /**
- * Lists all skill definitions stored in the knowledge base.
+ * Lists skill definitions stored in the knowledge base.
  *
- * Calls `client.listByType('skill')` and maps each record to a
- * summary that includes the argument count parsed from the JSON
- * content. Parse errors default the argument count to `0`.
+ * Calls `client.listByType('skill')` and returns a JSON envelope
+ * of matching skill names. When `options.args` is non-empty, the
+ * positional arguments are joined with a space and used as a
+ * case-insensitive substring filter against each skill's name
+ * and description. An empty query returns every skill.
  *
  * @param client - client used to list skill sections
- * @param _options - parsed CLI options (unused; reserved for future flags)
- * @returns a `CommandResult` containing a JSON array of skill summaries
+ * @param options - parsed CLI options; positional `args` build
+ *   the filter query
+ * @returns a `CommandResult` with a JSON envelope
+ *   (`{ items, total, offset }`) of matching skill names
  */
-export declare function runSkillList(client: SkillListClient, _options: CliOptions): Promise<CommandResult>;
+export declare function runSkillList(client: SkillListClient, options: CliOptions): Promise<CommandResult>;
 export {};

package/dist/src/shared/cli/functions/split-markdown-sections.function.d.ts

@@ -0,0 +1,16 @@
+import type { MarkdownSection } from '../typings/markdown-section.interface.ts';
+/**
+ * Splits markdown content into sections on ATX heading
+ * boundaries (`# Title` through `###### Title`). Headings inside
+ * fenced code blocks are treated as plain text. A document with
+ * no headings is returned as one titleless section.
+ *
+ * Thin backward-compatible wrapper over the shared
+ * `splitMarkdown` strategy in `content-splitter`, stripping its
+ * `parentIndex` field for callers that predate section nesting.
+ *
+ * @param content - raw markdown document text
+ * @returns sections in document order, with trailing whitespace
+ *   trimmed from each section's body
+ */
+export declare function splitMarkdownSections(content: string): MarkdownSection[];

package/dist/src/shared/cli/typings/learn-client.interface.d.ts

@@ -1,3 +1,4 @@
+import type { AddSectionResult } from '../../worker-client/typings/add-section-result.model.ts';
 /**
  * Minimal client interface required by `runLearn`.
  *
@@ -9,8 +10,8 @@ export interface LearnClient {
      * Ingests a content section into the knowledge base.
      *
      * @param params - section metadata and raw text content
-     * @returns enriched result containing the new kbid plus
-     *   optional supersession, warnings, and near-duplicate info
+     * @returns result containing the new kbid plus optional
+     *   supersession, warnings, and near-duplicate info
      */
     addSection(params: {
         sectionType: string;
@@ -25,32 +26,19 @@ export interface LearnClient {
          * via source key when `replace` is `true`.
          */
         sourcePath?: string;
-    }): Promise<LearnAddSectionResult>;
-}
-/** Enriched add-section result returned by the daemon. */
-export interface LearnAddSectionResult {
-    /** List of knowledge-base identifiers assigned. */
-    readonly items: string[];
-    /** Number of items in the result set. */
-    readonly total: number;
-    /** Offset into the result set (always 0 for learn). */
-    readonly offset: number;
-    /**
-     * Kbid of the section superseded via `--replace`,
-     * or `null` / `undefined` when none.
-     */
-    readonly superseded?: string | null;
+        /** Hierarchical level (1-6) assigned to the section. */
+        level?: number;
+        /** KBID of the parent section for nesting. */
+        parent?: string;
+    }): Promise<AddSectionResult>;
     /**
-     * Advisory warning strings (e.g. `"heading_missing"`).
-     * May be absent from older daemon versions.
-     */
-    readonly warnings?: string[];
-    /**
-     * Near-duplicate sections with similarity >= 0.85.
-     * May be absent from older daemon versions.
+     * Groups a set of sections under a named document, creating the
+     * shared `DocumentManifest` for a markdown file split on
+     * headings.
+     *
+     * @param title - human-readable document title
+     * @param kbids - identifiers of the sections to group
+     * @returns the assigned document identifier
      */
-    readonly near_duplicates?: {
-        readonly kbid: string;
-        readonly similarity: number;
-    }[];
+    groupSections(title: string, kbids: string[]): Promise<string>;
 }

package/dist/src/shared/cli/typings/learn-result.model.d.ts

@@ -31,4 +31,6 @@ export interface LearnResult {
         kbid: string;
         similarity: number;
     }[];
+    /** Kbid of the parent section for nesting, or `undefined`. */
+    parent?: string;
 }

package/dist/src/shared/cli/typings/markdown-section.interface.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A single section of a markdown document produced by splitting
+ * on ATX heading boundaries (`# Title` through `###### Title`).
+ */
+export interface MarkdownSection {
+    /**
+     * Heading text for this section, trimmed of surrounding
+     * whitespace. Omitted for content that precedes the first
+     * heading in the document.
+     */
+    title?: string;
+    /**
+     * ATX heading depth (1-6), derived from the number of `#`
+     * characters. Omitted when `title` is omitted.
+     */
+    level?: number;
+    /**
+     * Body text belonging to this section -- everything between
+     * this section's heading (exclusive) and the next heading
+     * (exclusive), with trailing whitespace trimmed.
+     */
+    content: string;
+}

package/dist/src/shared/content-splitter/classes/heading-parent-tracker.class.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tracks nesting of headings by depth to resolve each new
+ * heading's parent section index. Shared by splitters whose
+ * sections nest by a numeric depth (markdown, HTML).
+ */
+export declare class HeadingParentTracker {
+    private readonly stack;
+    /**
+     * Resolves the parent index for a heading at `level`
+     * appearing at output position `index`, then records the
+     * heading so subsequent, deeper headings can nest under it.
+     *
+     * @param level - heading depth, shallower is smaller
+     * @param index - position of this heading in the output
+     *   sections array
+     * @returns the parent's output index, or `null` when the
+     *   heading is at the root
+     */
+    resolve(level: number, index: number): number | null;
+}

package/dist/src/shared/content-splitter/constants/content-type-maps.constant.d.ts

@@ -0,0 +1,5 @@
+import type { ContentFormat } from '../typings/content-format.type.ts';
+/** Explicit type hints (MIME or short-form) mapped to format. */
+export declare const HINT_FORMAT_MAP: Record<string, ContentFormat>;
+/** File extensions (without the leading dot) mapped to format. */
+export declare const EXTENSION_FORMAT_MAP: Record<string, ContentFormat>;

package/dist/src/shared/content-splitter/constants/split-strategy-map.constant.d.ts

@@ -0,0 +1,4 @@
+import type { ContentFormat } from '../typings/content-format.type.ts';
+import type { SplitStrategy } from '../typings/split-strategy.interface.ts';
+/** Maps each recognized content format to its split strategy. */
+export declare const SPLIT_STRATEGY_MAP: Record<ContentFormat, SplitStrategy>;

package/dist/src/shared/content-splitter/functions/detect-content-type.function.d.ts

@@ -0,0 +1,13 @@
+import type { ContentFormat } from '../typings/content-format.type.ts';
+/**
+ * Detects the content format of a document, preferring an
+ * explicit type hint, then a file extension, then sniffing
+ * the content itself, and finally falling back to plain text.
+ *
+ * @param content - raw document text
+ * @param typeHint - explicit MIME type or short-form hint
+ *   (e.g. `'text/markdown'`, `'markdown'`)
+ * @param filePath - source file path used to infer format
+ *   from its extension
+ */
+export declare function detectContentType(content: string, typeHint?: string, filePath?: string): ContentFormat;

package/dist/src/shared/content-splitter/functions/flush-markdown-draft.function.d.ts

@@ -0,0 +1,14 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+import type { HeadingParentTracker } from '../classes/heading-parent-tracker.class.ts';
+import type { MarkdownDraft } from '../typings/markdown-draft.interface.ts';
+/**
+ * Appends `draft` to `sections`, resolving its parent index
+ * via `tracker`. An empty, titleless draft (no accumulated
+ * preamble) is skipped.
+ *
+ * @param draft - accumulated section awaiting output
+ * @param sections - output array to append to, mutated in
+ *   place
+ * @param tracker - depth stack shared across a single split
+ */
+export declare function flushMarkdownDraft(draft: MarkdownDraft, sections: ContentSection[], tracker: HeadingParentTracker): void;

package/dist/src/shared/content-splitter/functions/flush-toml-draft.function.d.ts

@@ -0,0 +1,15 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+import type { TomlDraft } from '../typings/toml-draft.interface.ts';
+/**
+ * Appends `draft` to `sections`, resolving its parent index
+ * via `pathIndex`. An empty, titleless draft (no accumulated
+ * preamble) is skipped. Registers titled drafts in
+ * `pathIndex` so later dotted headers can nest under them.
+ *
+ * @param draft - accumulated section awaiting output
+ * @param sections - output array to append to, mutated in
+ *   place
+ * @param pathIndex - lookup from header path to output index,
+ *   mutated in place
+ */
+export declare function flushTomlDraft(draft: TomlDraft, sections: ContentSection[], pathIndex: Map<string, number>): void;

package/dist/src/shared/content-splitter/functions/push-content-section.function.d.ts

@@ -0,0 +1,16 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+import type { HeadingParentTracker } from '../classes/heading-parent-tracker.class.ts';
+/**
+ * Appends a section to `sections`, resolving its
+ * `parentIndex` via `tracker` when it carries a heading
+ * `level`. Shared by depth-nested splitters (markdown, HTML)
+ * so nesting logic is defined once.
+ *
+ * @param sections - output array to append to, mutated in
+ *   place
+ * @param tracker - depth stack shared across a single split
+ * @param content - section body content
+ * @param title - heading text, omitted for root content
+ * @param level - heading depth, omitted for root content
+ */
+export declare function pushContentSection(sections: ContentSection[], tracker: HeadingParentTracker, content: string, title?: string, level?: number): void;

package/dist/src/shared/content-splitter/functions/resolve-parent-ids.function.d.ts

@@ -0,0 +1,14 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+/**
+ * Resolves each section's `parentIndex` to the KBDB id of the
+ * section that was stored at that index. Used after sections
+ * have been persisted in order, to link children to parents.
+ *
+ * @param sections - split sections, in the same order as
+ *   `kbids`
+ * @param kbids - persisted section ids, one per `sections`
+ *   entry
+ * @returns one parent id per section, or `null` for
+ *   root-level sections
+ */
+export declare function resolveParentIds(sections: readonly ContentSection[], kbids: readonly string[]): (string | null)[];

package/dist/src/shared/content-splitter/functions/split-content.function.d.ts

@@ -0,0 +1,11 @@
+import type { SplitResult } from '../typings/split-result.interface.ts';
+/**
+ * Splits `content` into sections using the strategy matching
+ * its detected format. Detection prefers `typeHint`, then
+ * `filePath`'s extension, then sniffs the content itself.
+ *
+ * @param content - raw document text
+ * @param typeHint - explicit MIME type or short-form hint
+ * @param filePath - source file path used to infer format
+ */
+export declare function splitContent(content: string, typeHint?: string, filePath?: string): SplitResult;

package/dist/src/shared/content-splitter/functions/split-html.function.d.ts

@@ -0,0 +1,12 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+/**
+ * Splits HTML content into sections on `<h1>` through `<h6>`
+ * tag boundaries, using regex matching rather than DOM
+ * parsing. Each heading section's `parentIndex` points to the
+ * nearest enclosing heading of a shallower depth.
+ *
+ * @param content - raw HTML document text
+ * @returns sections in document order, trailing whitespace
+ *   trimmed from each section's body
+ */
+export declare function splitHtml(content: string): ContentSection[];

package/dist/src/shared/content-splitter/functions/split-markdown.function.d.ts

@@ -0,0 +1,13 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+/**
+ * Splits markdown content into sections on ATX heading
+ * boundaries (`# Title` through `###### Title`). Headings
+ * inside fenced code blocks are treated as plain text. Each
+ * heading section's `parentIndex` points to the nearest
+ * enclosing heading of a shallower depth.
+ *
+ * @param content - raw markdown document text
+ * @returns sections in document order, trailing whitespace
+ *   trimmed from each section's body
+ */
+export declare function splitMarkdown(content: string): ContentSection[];

package/dist/src/shared/content-splitter/functions/split-plain-text.function.d.ts

@@ -0,0 +1,8 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+/**
+ * Passthrough splitter for unrecognized content formats.
+ * Wraps the entire input in a single root-level section.
+ *
+ * @param content - raw document text
+ */
+export declare function splitPlainText(content: string): ContentSection[];

package/dist/src/shared/content-splitter/functions/split-toml.function.d.ts

@@ -0,0 +1,12 @@
+import type { ContentSection } from '../typings/content-section.interface.ts';
+/**
+ * Splits TOML content into sections on `[table]` header
+ * boundaries. A dotted header (`[a.b]`) nests under the
+ * section matching its prefix (`[a]`); an undotted or quoted
+ * header is a root-level section.
+ *
+ * @param content - raw TOML document text
+ * @returns sections in document order, trailing whitespace
+ *   trimmed from each section's body
+ */
+export declare function splitToml(content: string): ContentSection[];

package/dist/src/shared/content-splitter/index.d.ts

@@ -0,0 +1,11 @@
+export { splitContent } from './functions/split-content.function.ts';
+export { splitMarkdown } from './functions/split-markdown.function.ts';
+export { splitHtml } from './functions/split-html.function.ts';
+export { splitToml } from './functions/split-toml.function.ts';
+export { splitPlainText } from './functions/split-plain-text.function.ts';
+export { detectContentType } from './functions/detect-content-type.function.ts';
+export { resolveParentIds } from './functions/resolve-parent-ids.function.ts';
+export type { ContentSection } from './typings/content-section.interface.ts';
+export type { SplitResult } from './typings/split-result.interface.ts';
+export type { SplitStrategy } from './typings/split-strategy.interface.ts';
+export type { ContentFormat } from './typings/content-format.type.ts';

package/dist/src/shared/content-splitter/typings/content-format.type.d.ts

@@ -0,0 +1,2 @@
+/** Content formats recognized by the content splitter. */
+export type ContentFormat = 'markdown' | 'html' | 'toml' | 'plain-text';

package/dist/src/shared/content-splitter/typings/content-section.interface.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A section produced by a content splitter.
+ * Depth-first ordered within the document.
+ */
+export interface ContentSection {
+    /** Section heading text, if any. */
+    title?: string;
+    /** Heading depth (1-6), if detected. */
+    level?: number;
+    /** Section body content. */
+    content: string;
+    /**
+     * Index of the parent section in the output
+     * array, or `null` for root-level sections.
+     */
+    parentIndex: number | null;
+}

package/dist/src/shared/content-splitter/typings/markdown-draft.interface.d.ts

@@ -0,0 +1,12 @@
+/**
+ * In-progress markdown section accumulated while scanning
+ * document lines, before it is flushed into a `ContentSection`.
+ */
+export interface MarkdownDraft {
+    /** Heading text, omitted while accumulating preamble. */
+    title?: string;
+    /** Heading depth (1-6), omitted while accumulating preamble. */
+    level?: number;
+    /** Body lines collected since the last heading. */
+    lines: string[];
+}

package/dist/src/shared/content-splitter/typings/split-result.interface.d.ts

@@ -0,0 +1,8 @@
+import type { ContentSection } from './content-section.interface.ts';
+/** Result of splitting content by format. */
+export interface SplitResult {
+    /** Extracted sections, depth-first ordered. */
+    sections: ContentSection[];
+    /** Detected content format identifier. */
+    format: string;
+}

package/dist/src/shared/content-splitter/typings/split-strategy.interface.d.ts

@@ -0,0 +1,3 @@
+import type { ContentSection } from './content-section.interface.ts';
+/** Splits raw content into sections. */
+export type SplitStrategy = (content: string) => ContentSection[];

package/dist/src/shared/content-splitter/typings/toml-draft.interface.d.ts

@@ -0,0 +1,15 @@
+/**
+ * In-progress TOML section accumulated while scanning
+ * document lines, before it is flushed into a `ContentSection`.
+ */
+export interface TomlDraft {
+    /** Header text, omitted while accumulating preamble. */
+    title?: string;
+    /**
+     * Header text used for dotted-parent lookup, identical to
+     * `title` unless the header is quoted.
+     */
+    path?: string;
+    /** Body lines collected since the last header. */
+    lines: string[];
+}

package/dist/src/shared/mcp/functions/build-learn-payload.function.d.ts

@@ -0,0 +1,24 @@
+import type { AddSectionResult, NearDuplicateEntry } from '../../worker-client/typings/add-section-result.model.ts';
+/** JSON-serializable result envelope returned by the `learn` tool. */
+export interface LearnPayload {
+    /** Knowledge-base identifiers of all stored sections. */
+    readonly items: string[];
+    /** Number of items in the result set. */
+    readonly total: number;
+    /** Offset into the result set (always 0 for learn). */
+    readonly offset: number;
+    /** Kbid of a superseded section, or `null` if none. */
+    readonly superseded: string | null;
+    /** Advisory warnings emitted during indexing. */
+    readonly warnings: string[];
+    /** Near-duplicate sections detected above the threshold. */
+    readonly near_duplicates: NearDuplicateEntry[];
+}
+/**
+ * Normalizes an `AddSectionResult` into the `learn` tool's JSON
+ * result envelope, defaulting optional fields to their empty
+ * representation.
+ *
+ * @param result - the raw result from storing one or more sections
+ */
+export declare function buildLearnPayload(result: AddSectionResult): LearnPayload;

package/dist/src/shared/mcp/functions/determine-learn-split.function.d.ts

@@ -0,0 +1,18 @@
+import type { SplitResult } from '../../content-splitter/index.ts';
+/**
+ * Determines whether `learn` content should be imported as
+ * multiple linked sections instead of one, and returns the split
+ * result when it should.
+ *
+ * Splitting applies only when no explicit `title` is given, the
+ * section type is a splittable text format (`text/*` or the bare
+ * `'markdown'` alias), and splitting produces at least two
+ * sections with at least one heading title.
+ *
+ * @param content - raw content to evaluate for splitting
+ * @param sectionType - the section's semantic type label
+ * @param title - explicit title from the caller, if any
+ * @returns the split result when splitting should apply,
+ *   otherwise `undefined`
+ */
+export declare function determineLearnSplit(content: string, sectionType: string, title: string | undefined): SplitResult | undefined;