/**
 * CLI-instructions scan for Neotoma CLI.
 * Scans project and user-level rule locations for "prefer MCP when available, CLI as backup"
 * and offers to add a canonical snippet so it is applied in Cursor, Claude Code, and Codex.
 *
 * Only paths where each IDE actually loads rules count as "applied":
 * - Cursor: .cursor/rules/* (not docs/ unless synced there)
 * - Claude: .claude/CLAUDE.md, .claude/rules/*
 * - Codex: .codex/neotoma_cli.md (project), ~/.codex/ (user)
 */
/**
 * Inject or replace the active-env section in instruction body content.
 * Inserts after the first top-level heading. If an env section is already present,
 * replaces it in place so the rest of the content is preserved.
 */
export declare function buildEnvSpecificInstructions(body: string, env: "dev" | "prod"): string;
/**
 * Silently update the active environment section in the project-level cursor rule file.
 * Called on CLI session start to keep the rule file in sync with the current env.
 * Breaks symlinks (replaces with real files) so the env section can be written.
 * Returns true if the file was updated.
 */
export declare function autoUpdateCliInstructionsEnv(projectRoot: string, env: "dev" | "prod"): Promise<boolean>;
export interface ScanResultLocation {
    path: string;
    hasInstruction: boolean;
    label?: string;
}
/** Per-environment applied status: instruction present in a path that the IDE actually loads. */
export interface AppliedStatus {
    cursor: boolean;
    claude: boolean;
    codex: boolean;
}
export interface AgentInstructionsScanResult {
    projectRoot: string;
    project: ScanResultLocation[];
    user: ScanResultLocation[];
    /** Applied in each environment (project or user). Based on exact rule file at expected path. */
    applied: AppliedStatus;
    /** Applied in project-level paths only (.cursor/rules, .claude, .codex). */
    appliedProject: AppliedStatus;
    /** Applied in user-level paths only (~/.cursor/rules, ~/.claude, ~/.codex). */
    appliedUser: AppliedStatus;
    /** True if rule file exists but content does not match current doc (needs update). */
    staleProject: AppliedStatus;
    /** True if rule file exists but content does not match current doc (needs update). */
    staleUser: AppliedStatus;
    /** True if instruction is missing in any applied environment. */
    missingInApplied: boolean;
    /** True if any applied path has outdated content (should run add/update to load latest). */
    needsUpdateInApplied: boolean;
    /** Legacy: true if any scanned project file has it (includes docs). */
    missingInProject: boolean;
    /** Legacy: true if no user-level scanned file has it. */
    missingInUser: boolean;
    /** True if applied rule at this path is a symlink (project: symlink to doc; user: always false by design). */
    symlinkProject: AppliedStatus;
    /** True if applied rule at this path is a symlink. */
    symlinkUser: AppliedStatus;
}
/**
 * Scan project and optionally user-level paths for "prefer Neotoma CLI when local" instruction.
 */
export declare function scanAgentInstructions(startDir: string, options?: {
    includeUserLevel?: boolean;
}): Promise<AgentInstructionsScanResult>;
/** Path to the CLI agent instructions doc (source of truth), relative to project root. */
export declare const CLI_AGENT_INSTRUCTIONS_DOC_PATH = "docs/developer/cli_agent_instructions.md";
/** Fallback rule content when the doc file is missing (e.g. packaged build). Used for snippet display in CLI. */
export declare const PREFER_CLI_RULE_CONTENT = "# Neotoma transport: MCP when available, CLI as backup\n\n## Purpose\n\nPrefer Neotoma MCP when it is installed and running in this environment; use the Neotoma CLI as backup when MCP is not available.\n\n## Rule\n\n- **When MCP is available:** Use MCP tools (`store`, create_relationship, etc.) per docs/developer/mcp/instructions.md.\n- **When MCP is not available:** Use `neotoma dev <command>` (e.g. neotoma dev entities list, neotoma dev store --json='...').\n\n## When to load\n\nLoad when configuring or documenting agent behavior, or when choosing between MCP and CLI for Neotoma operations.\n";
/**
 * Load CLI agent instruction content from the docs file. Strips leading YAML frontmatter if present.
 * Returns fallback content if the file is missing or unreadable.
 */
export declare function loadCliAgentInstructions(projectRoot: string): Promise<string>;
/**
 * Build the full content to write for a given target path. Adds frontmatter for .mdc files.
 */
export declare function buildRuleContentForTarget(body: string, targetPath: string): string;
/** Project-level applied paths where the rule file is written (one per environment). */
export declare const PROJECT_APPLIED_RULE_PATHS: {
    readonly cursor: ".cursor/rules/neotoma_cli.mdc";
    readonly claude: ".claude/rules/neotoma_cli.mdc";
    readonly codex: ".codex/neotoma_cli.md";
};
export type CliInstructionsScope = "project" | "user" | "both";
/**
 * Create a symlink from the project rule path to the doc file so the rule is always up to date.
 * Removes existing file or symlink at linkPath first. Fails if the doc does not exist.
 */
export declare function createSymlinkToDoc(projectRoot: string, linkPath: string): Promise<void>;
/**
 * Create a symlink from a user-level rule path to the doc file (absolute target).
 * Use when the link is outside the repo (e.g. ~/.cursor/rules/). Removes existing file or symlink first.
 */
export declare function createUserSymlinkToDoc(projectRoot: string, linkPath: string): Promise<void>;
/**
 * Write the rule content to a file. Creates parent dirs if needed.
 * Used for user-level paths (copy). Content should be the full body; frontmatter is added for .mdc.
 */
export declare function writePreferCliRule(targetPath: string, content: string): Promise<void>;
/**
 * Get user-level rule file path for each environment (platform-specific).
 */
export declare function getUserAppliedRulePaths(): {
    cursor: string;
    claude: string;
    codex: string;
} | null;
/**
 * Ask user to choose project-level or user-level (or both, or skip).
 * defaultChoice controls which option is pre-selected when the user presses Enter.
 * Returns "project" | "user" | "both" | null.
 */
export declare function askWhereToAdd(defaultChoice?: "1" | "2" | "3"): Promise<CliInstructionsScope | null>;
export interface ApplyCliInstructionsOptions {
    scope: CliInstructionsScope;
    env?: "dev" | "prod";
}
export declare function applyCliInstructions(result: AgentInstructionsScanResult, options: ApplyCliInstructionsOptions): Promise<{
    added: string[];
    skipped?: boolean;
}>;
/**
 * Offer to add or update the canonical rule so the latest version is applied in Cursor, Claude, and Codex.
 * Writes to applied paths when missing or stale (content does not match current doc).
 *
 * When `env` is provided the written files contain an env-specific "Active environment" section
 * and are written as real files (not symlinks). Without `env`, project paths are created as symlinks
 * so they stay in sync with the docs source automatically.
 */
export declare function offerAddPreferCliRule(result: AgentInstructionsScanResult, options?: {
    nonInteractive?: boolean;
    env?: "dev" | "prod";
    /** When set, use this scope without prompting (e.g. reuse MCP install choice). */
    scope?: CliInstructionsScope;
}): Promise<{
    added: string[];
    skipped?: boolean;
}>;
//# sourceMappingURL=agent_instructions_scan.d.ts.map