/**
 * Definitions on disk: how a `.md` with frontmatter is found and read.
 *
 * Agents and flows are the same file format, discovered the same way - a
 * directory of `.md` files, and a walk up the parents to the first
 * `.pi/<something>/`. Only what happens to a file *after* it is read differs,
 * and that difference is the point: `loadAgents` drops an agent that does not
 * parse in silence, a flow's catalogue collects it and reports it by name. So
 * this file finds and reads; it never decides what a file means.
 *
 * The frontmatter coercions live here too, because "YAML-ish" is a property of
 * the format rather than of either reader: a flag written `true` in a file
 * arrives as the string `"true"` about as often as a boolean.
 */
import type { AgentScope, AgentSource } from "./agent.ts";
/** One Markdown file, read. */
export type MarkdownFile = {
    /** Its full path - what an error message has to name. */
    filePath: string;
    /** The file name without `.md`: the fallback name of a definition that fails to parse. */
    name: string;
    /** Its whole content, frontmatter included. */
    content: string;
};
/**
 * Every readable `.md` in `dir`, by name.
 *
 * A missing or unreadable directory yields `[]`, and so does an unreadable
 * file: discovery scans places that legitimately do not exist - a repository
 * with no `.pi/`, a user who never made one - and a missing directory is not an
 * error to report, it is the normal case.
 *
 * Sorted, so two runs on the same directory load the same definitions in the
 * same order whatever the filesystem feels like returning.
 */
export declare function readMarkdownDir(dir: string): MarkdownFile[];
/** A directory definitions are read from, and whose they are. */
export type DefinitionDir = {
    dir: string;
    source: AgentSource;
};
/**
 * Where the definitions kept under `<sub>/` are looked for, **least specific
 * first**: the package's own (`builtinDir`, when it ships any) when `builtin`
 * is set, then the user's `~/.pi/agent/<sub>/`, then the repository's nearest
 * `.pi/<sub>/`.
 *
 * A caller reads them in this order into one map by name, so whoever is closer
 * to the work wins it. The scope defaults to `"user"`: a repository's
 * definitions are third-party instructions, loaded only on explicit request.
 */
export declare function definitionDirs(sub: string, builtinDir: string | undefined, options: {
    cwd?: string;
    scope?: AgentScope;
    builtin?: boolean;
}): DefinitionDir[];
/** Walks up from `cwd` to the first `.pi/<sub>/` that exists. */
export declare function findProjectDir(cwd: string, sub: string): string | undefined;
/**
 * A YAML error in a file's frontmatter, as one line: the reason, then the line
 * in the file. `yaml` counts from the first line of the frontmatter, which is
 * the file's second, after the opening `---`.
 */
export declare function yamlError(error: unknown): string;
/** Frontmatter text, trimmed. Blank counts as absent: `name:` with nothing after it says nothing. */
export declare function asString(value: unknown): string | undefined;
/**
 * A YAML-ish count: a positive whole number, however the parser handed it over.
 *
 * Anything else is `undefined` rather than coerced. `concurrency: 0` and
 * `concurrency: two` are typos, and a field that turned the first into "no
 * branches at all" would be a setting nobody meant to write.
 */
export declare function asCount(value: unknown): number | undefined;
/**
 * A YAML-ish list: a real sequence, or one line of comma-separated items.
 *
 * Empty counts as absent, item by item: `tools: read, , grep` names two tools,
 * and `skills:` with nothing after it names none - which is what lets a caller
 * tell "the file said nothing" from "the file said nothing useful".
 */
export declare function asList(value: unknown): string[] | undefined;
/** A YAML-ish flag: a boolean, or the text `"true"` / `"false"`. */
export declare function asBoolean(value: unknown): boolean | undefined;
//# sourceMappingURL=markdown.d.ts.map