/**
 * init-hints.mjs — one-time UX hints emitted at the tail of fresh
 * `apt-tools init` and first `apt-tools pr-review init-pr` invocations,
 * explaining which `.aperant/` files are intentionally team-shared
 * (committed) vs gitignored (ephemeral).
 *
 * Why: users routinely see `M .aperant/config.json` in `git status` after a
 * `/apt:setup` run and assume the framework forgot to gitignore it. They
 * are correct that it shows up — but wrong about the cause: `config.json`
 * is intentionally committable team-level prefs (per
 * `packages/framework/docs/artifact-lifecycle.md`'s classification table),
 * sitting next to ephemeral siblings like `state.json` and `team-status/`
 * that ARE gitignored. This printer closes that documented confusion with
 * a single stderr line at the right moment in each workflow.
 *
 * Stderr (not stdout) so the existing machine-readable JSON envelope from
 * `output()` stays parseable. Same channel as the gitignore-drift warning
 * (see `gitignore-drift.mjs` precedent).
 *
 * Suppressible via `APT_SUPPRESS_INIT_HINTS=1` for scripted/CI runs that
 * already understand the model — mirrors the
 * `APT_SUPPRESS_GITIGNORE_DRIFT=1` precedent.
 *
 * Callers are responsible for the "first-time only" gate (e.g. only call
 * `emitInitConfigHint` when `.aperant/config.json` was actually just
 * created — not on a noop re-install).
 *
 * @internal — consumed only from init.mjs and pr-review.mjs.
 */
/**
 * Returns true when the suppress env var is set to `'1'`. Centralized so
 * callers don't repeat the comparison.
 *
 * @returns {boolean}
 */
function isSuppressed() {
    return process.env.APT_SUPPRESS_INIT_HINTS === '1';
}
/**
 * One-time hint after a real `apt-tools init` (when `config.json` was
 * actually written fresh — NOT on noop re-install). Caller MUST gate on
 * the genuine "config created" signal.
 *
 * Single stderr line. Never throws. No-op when suppressed.
 *
 * @internal
 */
export function emitInitConfigHint() {
    if (isSuppressed())
        return;
    try {
        process.stderr.write('[apt-tools init] Note: .aperant/config.json is intentionally committed (team-shared framework prefs).\n' +
            '                       Commit it alongside your work. .aperant/state.json + team-status/ are gitignored\n' +
            '                       and never travel.\n');
    }
    catch {
        /* never block init on a hint write */
    }
}
/**
 * One-time hint after a real `apt-tools pr-review init-pr` (when
 * `pr-state.json` was just seeded — NOT on subsequent calls where the file
 * already exists / `rounds_completed > 0`). Caller MUST gate on the
 * genuine "state created" signal.
 *
 * Since 2026-04 the artifact is **ephemeral** (local framework coordination,
 * not a git artifact). The hint exists so users seeing the file under
 * `.aperant/pr-reviews/` know it's intentional local state and not stray
 * scratch — and so they don't try to commit it.
 *
 * Single stderr block. Never throws. No-op when suppressed.
 *
 * @param {number|string} prNumber  PR number, used for path-templating the
 *                                   hint so users can copy-paste the path.
 * @internal
 */
export function emitInitPrStateHint(prNumber) {
    if (isSuppressed())
        return;
    try {
        process.stderr.write(`[apt-tools pr-review init-pr] Note: .aperant/pr-reviews/pr-${prNumber}/pr-state.json is local-only\n` +
            '                                    (per-PR coordination — authorship pin, round counters, lock).\n' +
            '                                    Gitignored; auto-pruned by close-round on PR merge.\n');
    }
    catch {
        /* never block init-pr on a hint write */
    }
}
//# sourceMappingURL=init-hints.mjs.map