/** hq-root-relative location of the (locally-written) agent identity briefing. */
export declare const AGENTS_PROFILE_REL = "personal/agents-profile.md";
/** hq-root-relative dir holding the synced agent-capability overlay docs. */
export declare const AGENT_CAPABILITIES_REL = "personal/knowledge/public/agent-capabilities";
/** The capability doc carrying the operating contract — ordered first. */
export declare const AGENT_CONTRACT_FILE = "hq-agent-contract.md";
/** Leading marker so the file is self-describing and recognizable as generated. */
export declare const CODEX_AGENTS_MARKER = "<!-- hq-agent: generated by hq-sync-runner";
export interface CodexSection {
    /** hq-root-relative source path (for diagnostics; not written to the file). */
    name: string;
    content: string;
}
/**
 * Pure: compose the codex global `AGENTS.md` body from ordered sections.
 * Trims and drops empty/whitespace-only sections. Returns "" when nothing
 * substantive remains, so the caller can SKIP the write (never emit an
 * empty/marker-only file, never wipe a previously-materialized one).
 *
 * Deliberately carries NO timestamp: the output is a deterministic projection
 * of its inputs, so a no-change sync rewrites byte-identical content (no churn;
 * the write/skip/error events are timestamped in the diagnostic log instead).
 */
export declare function composeCodexAgentsMd(sections: CodexSection[]): string;
/**
 * Pure: order capability filenames — the operating contract first, then the
 * remaining `*.md` alphabetically. Non-markdown entries are dropped.
 */
export declare function orderCapabilityFiles(files: string[]): string[];
/**
 * IO: gather the agent overlay sections present under `hqRoot`. Order:
 *   1. identity briefing (`personal/agents-profile.md`)
 *   2. the operating contract (`agent-capabilities/hq-agent-contract.md`)
 *   3. any other `agent-capabilities/*.md`, alphabetically
 * Each is included only when it is a regular file and non-whitespace-only.
 * Symlinks and directories are skipped (containment / no symlink-escape).
 */
export declare function gatherCodexAgentSections(hqRoot: string): CodexSection[];
export interface MaterializeLog {
    (e: {
        event: string;
        message: string;
        err?: unknown;
        context?: Record<string, unknown>;
    }): void;
}
export interface MaterializeResult {
    written: boolean;
    path: string;
    sectionCount: number;
    skippedReason?: "empty-overlay" | "target-not-regular-file" | "error";
}
/**
 * Resolve the codex home dir. Honors `CODEX_HOME` only when it is an ABSOLUTE
 * path with no `..` traversal; otherwise falls back to `~/.codex` (an injected
 * relative/traversing value must not redirect the write off-target).
 */
export declare function codexHomeDir(): string;
/**
 * Best-effort: project the synced agent overlay into `~/.codex/AGENTS.md`.
 * Idempotent atomic rewrite (write entropy-named temp + rename). NEVER throws —
 * logs and returns a result.
 *
 * Non-destructive guarantees:
 *   - SKIPS (no write, no delete) when the overlay yields no content, so a
 *     transient empty/unsynced tree can never wipe a previously-materialized
 *     file. (Emits a distinct event when a prior file exists — a possible
 *     provisioning regression worth an operator's eye.)
 *   - SKIPS when the target already exists but is NOT a regular file (a symlink
 *     or directory), rather than silently clobbering an external config
 *     relationship (or failing opaquely with EISDIR).
 *   - On any write/rename failure, the entropy-named temp file is cleaned up so
 *     repeated failures can't accumulate `*.hq-tmp` orphans.
 *
 * First boot: before the first `--personal` sync lands, the overlay is absent
 * and this skips — the agent operates on the project `AGENTS.md` (charter)
 * alone until the first sync materializes the contract (~one cycle).
 */
export declare function materializeCodexAgents(opts: {
    hqRoot: string;
    codexHome?: string;
    log?: MaterializeLog;
}): MaterializeResult;
//# sourceMappingURL=agent-codex-instructions.d.ts.map