import type { EnvironmentName } from '../config/environments.js';
export declare const AGENTS_MD_FILE = "AGENTS.md";
/**
 * Where the current template is written when the creator's own file is kept. Under `.bitmagic/`
 * so it is gitignored and outside the publish fingerprint — a suggestion must not make a passing
 * verify stale, or taking the suggestion would cost a re-verify.
 */
export declare const AGENTS_MD_TEMPLATE_FILE: string;
export declare function hashAgentsMd(contents: string): string;
/**
 * The `## ` headings of a markdown document, in order.
 *
 * Section granularity is the level that survives ordinary editing: a creator who rewrites a
 * paragraph, or appends notes of their own, still has the section. Comparing whole files would
 * report "different" for every project that has ever been touched, which is noise rather than
 * information. `#` (the title) and `###` (sub-points within a section) are deliberately ignored.
 */
export declare function sectionHeadings(markdown: string): string[];
/**
 * Sections the current template has that theirs does not.
 *
 * Matched on the heading text, so a renamed heading reads as missing. That is the right way to be
 * wrong for a suggestion nobody is forced to act on: a false positive costs a line of output, a
 * false negative silently withholds the guidance this exists to deliver.
 */
export declare function missingSections(theirs: string, ours: string): string[];
export type AgentsMdAction = 
/** Did not exist — written fresh. */
'created'
/** Byte-identical to the stamp, so replaced with the current template. */
 | 'rewritten'
/** Already the current template. Nothing to do, nothing to say. */
 | 'current'
/** Carries edits (or predates stamping) — left exactly as it was. */
 | 'kept';
export interface AgentsMdOutcome {
    action: AgentsMdAction;
    /** The stamp to record, or undefined to leave whatever is already there alone. */
    hashToStore?: string;
    /** Only for `kept`: sections of the current template their file does not have. */
    missingSections: string[];
    /** Only for `kept` with something to show: where the current template was written. */
    templatePath?: string;
}
/**
 * Bring a project's AGENTS.md up to date as far as is provably safe, and report what to tell the
 * creator. See the file header for the rule; this is where it is applied.
 *
 * `storedHash` is `bitmagic.json`'s `agentsMdHash` — absent for any project scaffolded before this
 * existed, which is exactly the population that most needs the suggestion path.
 *
 * `skillDirs` is passed for the same reason `environment` is: the template names the skills
 * directories the project actually holds, so a Kiro project's copy differs from a default one's.
 */
export declare function reconcileAgentsMd(root: string, storedHash: string | undefined, environment: EnvironmentName | undefined, skillDirs?: readonly string[]): AgentsMdOutcome;