/**
 * CLI context transparency helper.
 *
 * Agent-first output: default is minimal (just the command result), so
 * tool-calling agents don't see a wall of prose. When the user passes
 * `-v` / `--verbose` (or sets `PHOTON_VERBOSE=1`), commands emit `→`
 * prefixed context lines showing PHOTON_DIR, the resolved photon, and
 * the target path. When the user passes `--json`, the command includes
 * a structured `context` envelope in its output.
 *
 * Rule of thumb for adopters: any command whose behavior depends on
 * which PHOTON_DIR is resolved should call `announceContext()` once at
 * entry so a user running `-v` can audit the decision. Commands that
 * already support `--json` should merge `contextEnvelope()` into their
 * response envelope.
 *
 * See docs/internals/PHOTON-DIR-AND-NAMESPACE.md and the codebase audit
 * (§10) for the full list of PHOTON_DIR-sensitive commands and the
 * migration status.
 */
export interface AnnounceOptions {
    /** Photon this operation targets, if applicable. */
    photon?: string;
    /** Verb for the primary action, e.g. "Creating", "Loading". */
    action?: string;
    /** Absolute path being acted on (created, loaded, written, etc.). */
    target?: string;
    /** Short hint line shown after the context. */
    hint?: string;
    /** Override verbosity detection (defaults to scanning argv / env). */
    verbose?: boolean;
}
export interface ContextEnvelope {
    /** Resolved PHOTON_DIR for this invocation. */
    photonDir: string;
    /** Data root for this invocation ({PHOTON_DIR}/.data/). */
    dataDir: string;
    photon?: string;
    action?: string;
    target?: string;
}
/** True when the caller opted into transparency via argv or env. */
export declare function isVerbose(): boolean;
/** Build the structured context envelope for `--json` mode. */
export declare function contextEnvelope(opts?: AnnounceOptions): ContextEnvelope;
/**
 * Print transparency lines to stderr when verbose is enabled. No-op
 * otherwise so default output stays clean for agents and scripts.
 */
export declare function announceContext(opts?: AnnounceOptions): void;
//# sourceMappingURL=announce-context.d.ts.map