@pugi/cli 0.1.0-beta.21 → 0.1.0-beta.23

package/dist/runtime/cli.js

@@ -22,17 +22,27 @@ import { PUGI_TAGLINE } from '@pugi/personas';
 import { resolveRoster, renderRosterTable } from './commands/roster.js';
 import { runDelegateCommand } from './commands/delegate.js';
 import { clearApiKey, DEFAULT_API_URL, listStoredCredentials, maskApiKey, normalizeApiUrl, purgeAllCredentials, readCredentialsFile, resolveActiveCredential, storeApiKey, switchActiveAccount, } from '../core/credentials.js';
+import { resolveAndValidateEnvLogin, } from '../core/auth/env-provider.js';
 import { runDeployCommand } from '../commands/deploy.js';
 import { runJobsCommand } from '../commands/jobs.js';
 import { runConfigCommand } from './commands/config.js';
+import { runStyleCommand } from './commands/style.js';
+import { runThemeCommand } from './commands/theme.js';
+import { runOnboardingCommand } from './commands/onboarding.js';
+import { runVimCommand } from './commands/vim.js';
+import { isOnboarded } from '../core/onboarding/marker.js';
 import { runPrivacyCommand } from './commands/privacy.js';
 import { runReport } from './commands/report.js';
 import { runDoctorCommand, defaultHome as defaultDoctorHome } from './commands/doctor.js';
 import { runStatusCommand, defaultStatusHome, } from './commands/status.js';
+import { runStickersCommand } from './commands/stickers.js';
+import { runReleaseNotesCommand, defaultReleaseNotesHome, } from './commands/release-notes.js';
 import { runUndoCommand } from './commands/undo.js';
 import { runCompactCommand } from './commands/compact.js';
 import { runBudgetCommand } from './commands/budget.js';
+import { BARE_MODE_BANNER, isBareMode, setBareMode, } from '../core/bare-mode/index.js';
 import { runCostCommand } from './commands/cost.js';
+import { runShareCommand } from './commands/share.js';
 import { runSkillsCommand } from './commands/skills.js';
 import { installDefaultSkills } from '../core/skills/defaults.js';
 import { runAgentsCommand } from './commands/agents.js';
@@ -43,6 +53,7 @@ import { resolveWorkspaceLabel } from '../core/repl/workspace-context.js';
 import { runReviewConsensus } from './commands/review-consensus.js';
 import { runMcpCommand } from './commands/mcp.js';
 import { runPermissionsCommand } from './commands/permissions.js';
+import { runPlanCommand } from './commands/plan.js';
 import { parsePermissionMode } from '../core/permissions/index.js';
 import { DECOMPOSE_PROMPT_SUFFIX, parseDecompositionFromText, writeDecomposition, } from './plan-decompose.js';
 import { FtsSyntaxError, SqliteSessionStore, resolveProjectStoreDir } from '../core/repl/store/index.js';
@@ -94,9 +105,15 @@ const handlers = {
     patch: dispatchPatch,
     permissions: dispatchPermissions,
     perms: dispatchPermissions,
-    plan: runEngineTask('plan'),
+    plan: dispatchPlan,
     'plan-review': dispatchPlanReview,
     privacy: dispatchPrivacy,
+    // L24 (2026-05-27): `pugi release-notes` shows the bundled CHANGELOG
+    // diff between the operator's last-seen version + installed version.
+    // The slash counterpart `/release-notes` shares this handler via the
+    // shared `runReleaseNotesCommand` runner.
+    'release-notes': releaseNotes,
+    releaseNotes,
     // PAVF-7 (2026-05-27): `pugi report --from-error` captures the
     // most-recent failed session as a redacted bundle so operators can
     // file clean bug reports without manual log-grepping.
@@ -105,9 +122,29 @@ const handlers = {
     resume,
     roster: dispatchRoster,
     sessions,
+    share: dispatchShare,
     skills: dispatchSkills,
     status,
+    stickers,
+    // Leak L21 (2026-05-27): in-CLI feedback collector. Shares the
+    // same handler as the in-REPL `/feedback` slash; the wrapper just
+    // routes TTY vs non-TTY before mounting Ink.
+    feedback: dispatchFeedback,
     sync,
+    style: dispatchStyle,
+    // Leak L30 (2026-05-27): `pugi theme` flips the local TUI color
+    // palette (orthogonal to `pugi style` — that one steers engine
+    // prose register). 4 presets: default / dark / light / colorblind.
+    theme: dispatchTheme,
+    // Leak L25 (2026-05-27): `pugi onboarding` walks the new operator
+    // through auth / mode / style / MCP / telemetry. Idempotent;
+    // `--reset` clears the marker file so the bare-invocation hint
+    // re-arms without nuking persisted defaults.
+    onboarding: dispatchOnboarding,
+    // Leak L26 (2026-05-27): `pugi vim` toggles vim-style modal editing
+    // in the REPL input buffer. Bare invocation toggles, `on`/`off`
+    // sets explicitly; preference persists in ~/.pugi/config.json.
+    vim: dispatchVim,
     undo: dispatchUndo,
     compact: dispatchCompact,
     // L19 (2026-05-27): `pugi usage` is an alias of `pugi cost` — same
@@ -288,6 +325,101 @@ async function dispatchPrivacy(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L18 (2026-05-27) — `pugi style` top-level dispatcher.
+ *
+ * Forwards to the shared `runStyleCommand` runner. The REPL `/style`
+ * slash uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy:
+ *   - 0 — show / switch / reset / list happy paths
+ *   - 1 — unknown preset slug
+ *   - 2 — conflicting flags (`--reset` + positional / `--reset --persist`)
+ *
+ * The runner returns the code; we attach it to `process.exitCode` so
+ * subsequent dispatch wrappers do not clobber it on success.
+ */
+async function dispatchStyle(args, flags, _session) {
+    const rc = await runStyleCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L30 (2026-05-27) — `pugi theme` top-level dispatcher.
+ *
+ * Forwards to the shared `runThemeCommand` runner. The REPL `/theme`
+ * slash uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy mirrors `dispatchStyle`:
+ *   - 0 — show / switch / reset / list happy paths
+ *   - 1 — unknown preset slug
+ *   - 2 — conflicting flags (`--reset` + positional / `--reset --persist`)
+ *
+ * The runner returns the code; we attach it to `process.exitCode` so
+ * subsequent dispatch wrappers do not clobber it on success.
+ */
+async function dispatchTheme(args, flags, _session) {
+    const rc = await runThemeCommand(args, {
+        workspaceRoot: process.cwd(),
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L25 (2026-05-27) — `pugi onboarding` top-level dispatcher.
+ *
+ * Walks the new operator through auth / permission mode / output
+ * style / MCP / telemetry consent. The Ink wizard mounts only when
+ * stdin is a TTY and `--json` is not set; otherwise we dump the
+ * current snapshot + hints in the non-interactive envelope so
+ * scripted callers see the same structured payload.
+ *
+ * Auth status: we resolve credentials once up front and pass the
+ * boolean to the runner; the wizard surfaces a `pugi login` hint
+ * when auth is missing but DOES NOT block — local defaults are still
+ * configurable without an active credential.
+ *
+ * Exit-code policy:
+ *   0 — completed / cancelled / non-interactive / reset
+ *   2 — conflicting / unknown flags
+ */
+async function dispatchOnboarding(args, flags, _session) {
+    const credential = resolveActiveCredential();
+    const rc = await runOnboardingCommand(args, {
+        workspaceRoot: process.cwd(),
+        env: process.env,
+        authPresent: credential !== null,
+        interactive: isInteractive(flags) && !flags.json,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
+/**
+ * Leak L26 (2026-05-27) — `pugi vim` top-level dispatcher.
+ *
+ * Forwards to the shared `runVimCommand` runner. The REPL `/vim` slash
+ * uses the same runner via a dynamic import inside
+ * `core/repl/session.ts` so the two surfaces stay single-sourced.
+ *
+ * Exit-code policy:
+ *   - 0 — show / enable / disable / toggle happy paths
+ *   - 2 — unknown subcommand (e.g. `pugi vim chaos`) or too many args
+ */
+async function dispatchVim(args, flags, _session) {
+    const rc = await runVimCommand(args, {
+        env: process.env,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+    if (rc !== 0)
+        process.exitCode = rc;
+}
 /**
  * PAVF-7 (2026-05-27): `pugi report --from-error` — bundle the most-
  * recent failed session into a redacted local report so operators can
@@ -438,6 +570,124 @@ async function dispatchCost(args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * Leak L20 (2026-05-27): `pugi share` top-level surface. Exports the
+ * current session transcript as Markdown to gist (default when `gh` is
+ * available) or pugi.io (--pugi). The handler delegates to
+ * `runShareCommand` so the slash surface (`/share`) and the shell
+ * surface share one code path. JSON output mode is honoured via the
+ * shared `writeOutput` wrapper.
+ */
+async function dispatchShare(args, flags, _session) {
+    await runShareCommand(args, {
+        workspaceRoot: process.cwd(),
+        cliVersion: PUGI_CLI_VERSION,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * Leak L7 — `pugi plan [--back | --persist | <prompt...>]`.
+ *
+ * Quick mode-switch shortcut + optional one-shot engine dispatch. Slash
+ * surface `/plan` shares the same `runPlanCommand` helper so the
+ * workspace-state writes go through one code path. Argument grammar:
+ *
+ *   pugi plan                    -> set workspace mode = plan + banner
+ *   pugi plan --back             -> restore the mode that was active
+ *                                   before the most recent /plan entry
+ *   pugi plan --persist          -> set + also write ~/.pugi/config.json
+ *   pugi plan <prompt...>        -> set + run `runEngineTask('plan')`
+ *                                   with the prompt (existing offline /
+ *                                   engine path; the permission gate now
+ *                                   sees plan as workspace state)
+ *   pugi plan <prompt> --auto-back  -> ALSO restore previous mode once
+ *                                       the engine returns (defaults to
+ *                                       leaving the operator in plan
+ *                                       mode so they can iterate)
+ *
+ * The handler intentionally intercepts the mode-switch flags BEFORE
+ * delegating to `runEngineTask('plan')` for the prompt path. Without
+ * this wrapper, `pugi plan` (no args) would error out of the engine
+ * task ("requires a prompt") which is the legacy behaviour; the L7
+ * spec wants bare `pugi plan` to be the mode switch.
+ */
+async function dispatchPlan(args, flags, session) {
+    // Strip `--back` / `--auto-back` from the positional args — the global
+    // parseArgs does not consume them (they are command-local). Anything
+    // else stays in `prompt` so the engine sees the operator's text
+    // verbatim. The flag parser keeps both `--back` and the spelling
+    // variants the operator might type from muscle memory after using
+    // `git checkout --` style flows.
+    let back = false;
+    let autoBack = false;
+    const remaining = [];
+    for (const arg of args) {
+        if (arg === '--back') {
+            back = true;
+        }
+        else if (arg === '--auto-back') {
+            autoBack = true;
+        }
+        else {
+            remaining.push(arg);
+        }
+    }
+    const hasPrompt = remaining.length > 0;
+    const persist = Boolean(flags.persist);
+    // --back and a prompt are mutually exclusive — back is a revert action,
+    // not a dispatch one. Refuse the combination with a clear hint instead
+    // of silently dropping one or the other.
+    if (back && hasPrompt) {
+        writeOutput(flags, { ok: false, error: 'pugi plan --back does not accept a prompt; revert first, then dispatch.' }, 'pugi plan --back does not accept a prompt; revert first, then dispatch.');
+        process.exitCode = 2;
+        return;
+    }
+    // --back + --auto-back is incoherent (auto-back applies to the
+    // dispatch path) — refuse rather than degrade silently.
+    if (back && autoBack) {
+        writeOutput(flags, { ok: false, error: 'pugi plan --back and --auto-back cannot be combined.' }, 'pugi plan --back and --auto-back cannot be combined.');
+        process.exitCode = 2;
+        return;
+    }
+    // When a prompt is going to be dispatched in --json mode, suppress
+    // the human-readable banner writes so the engine task remains the
+    // single JSON emitter on stdout. The mode write still happens. In
+    // human (non --json) mode the banner prints normally so the operator
+    // sees the gate-state change before the engine starts thinking.
+    const sinkSilent = hasPrompt && flags.json;
+    const writeLine = (line) => {
+        if (sinkSilent)
+            return;
+        writeOutput(flags, { text: line }, line);
+    };
+    const result = await runPlanCommand({ back, persist }, {
+        workspaceRoot: process.cwd(),
+        writeOutput: writeLine,
+    });
+    // No prompt → mode-switch only. Done.
+    if (!hasPrompt)
+        return;
+    // Prompt present → fall through to the existing engine task with the
+    // remaining args. The workspace mode is now `plan` (or stayed `plan`
+    // if already there); the engine sees the same plan-task semantics it
+    // always has — read-only schema + executor refusal sentinel — but the
+    // permission GATE now also enforces plan independently.
+    try {
+        await runEngineTask('plan')(remaining, flags, session);
+    }
+    finally {
+        // --auto-back restores the previous mode AFTER the engine returns
+        // (success OR failure) so the operator's gate state mirrors a normal
+        // `--back` invocation. Without --auto-back the operator stays in
+        // plan and can iterate / inspect before acting.
+        if (autoBack && (result.verdict === 'entered' || result.verdict === 'persisted')) {
+            await runPlanCommand({ back: true, persist: false }, {
+                workspaceRoot: process.cwd(),
+                writeOutput: writeLine,
+            });
+        }
+    }
+}
 async function dispatchSkills(args, flags, _session) {
     await runSkillsCommand(args, {
         workspaceRoot: process.cwd(),
@@ -567,6 +817,21 @@ async function dispatchWorktree(args, flags, _session) {
 }
 export async function runCli(argv) {
     const { command, args, flags, isBareInvocation } = parseArgs(argv);
+    // Leak L22 — print the one-line bare banner once per invocation when
+    // the flag is active and stdout is NOT bound for JSON consumption. The
+    // banner goes to stderr so it never lands in a `--json` envelope or a
+    // pipe-captured stdout stream; operators see it on the terminal,
+    // scripted callers stay clean. Suppressed for `pugi version` / `pugi
+    // help` (short, scripted-friendly surfaces) and when the operator
+    // sets PUGI_BARE without the flag (avoids double-printing across
+    // scripted nested invocations).
+    if (flags.bare &&
+        !flags.json &&
+        command !== 'version' &&
+        command !== 'help' &&
+        argv.includes('--bare')) {
+        process.stderr.write(`${BARE_MODE_BANNER}\n`);
+    }
     // β-headless dispatch (CEO directive 2026-05-27 "нужно тестирование по
     // кругу"): when `--print <brief>` is set we route to the headless
     // runner BEFORE the REPL / splash / command branches. The runner
@@ -598,6 +863,19 @@ export async function runCli(argv) {
         process.exitCode = exitCode;
         return;
     }
+    // Leak L25 (2026-05-27): first-run hint. When the operator types a
+    // bare `pugi` on a real TTY AND the onboarding marker is absent, drop
+    // a one-line hint on stderr BEFORE the REPL splash mounts. Stderr so
+    // the line never lands in a `--json` envelope or a scripted stdout
+    // pipe; suppressed when --json is set or the operator already walked
+    // the wizard. The marker check is best-effort — a fs glitch returns
+    // false and we print the hint, which is harmless.
+    if (isBareInvocation
+        && isInteractive(flags)
+        && !flags.json
+        && !isOnboarded(process.env)) {
+        process.stderr.write('Tip: run `pugi onboarding` to configure defaults.\n');
+    }
     // Bare `pugi` on a TTY enters the REPL-by-default agentic session
     // (Sprint α5.7, ADR-0056). The REPL is the customer-facing surface
     // that brings Pugi to parity with Claude Code / Codex CLI. When the
@@ -697,8 +975,31 @@ function parseArgs(argv) {
         // surface.
         persist: false,
         confirm: false,
+        // Leak L22 — `--bare` flag (skip project auto-discovery). Default
+        // honors the env var so a wrapper script that exports PUGI_BARE=1
+        // keeps the bit even when the operator forgets the flag, and the
+        // explicit flag overrides on the way through the loop below.
+        bare: isBareMode(),
+        // Leak L33 — `--ascii-only` for `pugi stickers`. Default off so the
+        // interactive surface keeps its boxed renderer; opt-in via flag
+        // for pipe / script use.
+        asciiOnly: false,
+        // Leak L24 — `--reset` for `pugi release-notes`. Default off so a
+        // bare invocation only surfaces new sections. Opt-in to force the
+        // full bundled changelog к re-render (clears the on-disk marker).
+        reset: false,
     };
     const args = [];
+    // Leak L22: scan for `--bare` BEFORE the early-return short-circuits
+    // below. Operators may pass `pugi --bare --version` or `pugi --bare
+    // --help` and the short-circuit return must still flip the bare bit
+    // so subprocesses + env-consulting modules see the activated state.
+    // The bit is idempotent — re-applied inside the main loop below for
+    // non-short-circuit paths.
+    if (argv.includes('--bare')) {
+        flags.bare = true;
+        setBareMode();
+    }
     // Sprint 2E: `pugi --version` / `-v` are universal install-test conventions
     // (npm uses --version on every published bin, Homebrew formula uses it in
     // the test block). Normalize them to the `version` command so users can
@@ -767,6 +1068,20 @@ function parseArgs(argv) {
             // at the global level for consistency with --no-splash / --no-tool-stream.
             flags.noDefaults = true;
         }
+        else if (arg === '--ascii-only') {
+            // Leak L33 — `pugi stickers --ascii-only` skips the Ink boxed
+            // renderer. Parsed globally so the dispatcher can pass the flag
+            // through to runStickersCommand without per-command argv slicing.
+            flags.asciiOnly = true;
+        }
+        else if (arg === '--reset') {
+            // Leak L24 — `pugi release-notes --reset` clears the on-disk
+            // `~/.pugi/.last-seen-version` marker so the full bundled
+            // changelog re-renders. Parsed globally for symmetry with the
+            // rest of the flag grammar; `runReleaseNotesCommand` is the
+            // single consumer today.
+            flags.reset = true;
+        }
         else if (arg === '--decompose') {
             // α6.8 EXTEND PR1: plan-only flag. Other engine commands ignore
             // it. Parsed globally for symmetry with the rest of the flag
@@ -917,6 +1232,16 @@ function parseArgs(argv) {
             // acknowledgement).
             flags.confirm = true;
         }
+        else if (arg === '--bare') {
+            // Leak L22: disable project auto-discovery for this invocation.
+            // Set BOTH the parsed flag and the process env so downstream
+            // modules consulting `isBareMode()` (markdown-traverse callsite,
+            // REPL auto-init gate, doctor probe, subprocess spawns) see a
+            // coherent activated state without re-threading the bit through
+            // every call signature.
+            flags.bare = true;
+            setBareMode();
+        }
         else {
             args.push(arg);
         }
@@ -1044,6 +1369,28 @@ const COMMAND_HELP_BODIES = {
         '  pugi config get privacy',
         '  pugi config set privacy=<mode>',
     ],
+    share: [
+        'pugi share — export the current session transcript (leak L20).',
+        '',
+        'Reads .pugi/events.jsonl, formats it as Markdown, and uploads to',
+        'either a GitHub Gist (`gh`-backed, default when `gh` is available)',
+        'or pugi.io (--pugi). Always prompts before upload unless --yes is',
+        'set. Refuses upload entirely if the transcript carries an active',
+        '`Bearer ` credential — re-run with --redact to scrub it first.',
+        '',
+        'Flags:',
+        '  --gist            Force gist target; refuses if gh CLI is absent.',
+        '  --pugi            Force pugi.io target (requires `pugi login`).',
+        '  --redact          Run PII scrubber before upload.',
+        '  --preview         Print the transcript to stdout WITHOUT upload.',
+        '  --yes, -y         Skip the y/n confirmation prompt.',
+        '  --json            Emit a structured JSON envelope only.',
+        '',
+        'Examples:',
+        '  pugi share                          Auto-pick + confirm.',
+        '  pugi share --preview --redact       See what would be shared.',
+        '  pugi share --gist --redact --yes    Scripted secret-gist upload.',
+    ],
     cost: [
         'pugi cost — token + USD breakdown for the current Pugi session.',
         '',
@@ -1093,7 +1440,8 @@ const COMMAND_HELP_BODIES = {
         'Interactive picker by default (browser OAuth / PAT / env). Non-interactive:',
         '  --provider device                                Device-flow OAuth.',
         '  --provider token --token <jwt>                   Pass a JWT directly.',
-        '  --provider env --env PUGI_API_KEY                Read from an env var.',
+        '  --provider env                                   Read PUGI_API_KEY (or --key) + verify via /api/pugi/health.',
+        '  --provider env --key <value> --skip-validate    Explicit key, no probe (CI bootstrap).',
     ],
     accounts: [
         'pugi accounts — manage stored credentials across endpoints.',
@@ -1155,6 +1503,45 @@ const COMMAND_HELP_BODIES = {
         'Useful in shell scripts that need a human-confirm before a destructive',
         'step. Exits 0 on yes, 1 on no, 2 on cancel.',
     ],
+    stickers: [
+        'pugi stickers — show a Pugi brand sticker (gimmick).',
+        '',
+        'Picks one of the curated pug-face ASCII variants at random and footers',
+        'it with a rotating brand quote. Brand-personality surface — never a gate.',
+        '',
+        '  --json                  Emit a structured envelope (id · caption · quote).',
+        '  --ascii-only            Plain stdout (no box, no dim accents) for scripting.',
+        '',
+        'Also available as /stickers from inside the REPL.',
+    ],
+    feedback: [
+        'pugi feedback — file a bug / feature / general comment from the CLI.',
+        '',
+        'Interactive five-step wizard:',
+        '  1. category (bug / feature / general / praise)',
+        '  2. rating (1-5 stars)',
+        '  3. comment (multi-line, Ctrl-D submits)',
+        '  4. include redacted last 5 turns? (y/n, default n)',
+        '  5. confirm submit (y/n, default y)',
+        '',
+        'On network failure the envelope is appended to',
+        '.pugi/feedback-queue.jsonl and drained on the next online session.',
+        '',
+        'Also available as /feedback from inside the REPL.',
+    ],
+    'release-notes': [
+        'pugi release-notes — show what changed since you last upgraded.',
+        '',
+        'Reads the bundled CHANGELOG.md, slices to sections strictly newer than',
+        '~/.pugi/.last-seen-version, renders Markdown to stdout, then bumps the',
+        'last-seen marker to the installed CLI version. Re-running is a no-op',
+        'until you upgrade again.',
+        '',
+        '  --json                  Emit a structured envelope (sections + meta).',
+        '  --reset                 Clear last-seen marker; re-render every section.',
+        '',
+        'Also available as /release-notes from inside the REPL.',
+    ],
     deploy: [
         'pugi deploy — trigger a vendor deployment from the bound Git source.',
         '',
@@ -1248,6 +1635,10 @@ async function help(args, flags, _session) {
         '                          Pairs with PUGI_HIDE_TOOL_STREAM=1.',
         '  --no-defaults           Skip bundled default-skills install on',
         '                          `pugi init`. Pairs with PUGI_INIT_NO_DEFAULTS=1.',
+        '  --bare                  Disable project auto-discovery — no PUGI.md /',
+        '                          AGENTS.md / CLAUDE.md / GEMINI.md walk-up, no',
+        '                          auto-init of .pugi/, no persona auto-load.',
+        '                          Pairs with PUGI_BARE=1.',
         '',
         PUGI_TAGLINE,
         'Execution defaults to local. Use --remote or --web to create a handoff bundle.',
@@ -1301,6 +1692,111 @@ async function status(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi stickers` — Leak L33 (2026-05-27). Brand-personality gimmick
+ * mirroring Claude Code's `/stickers` easter egg. Picks one curated
+ * pug-face ASCII variant at random + footers it with a rotating quote
+ * from the Pugi brand corpus. Always exits 0 — never a gate.
+ *
+ * The handler stays thin: corpus + picker + pure renderers live in
+ * `tui/stickers-art.tsx`; this wrapper just hands the resolved result
+ * к the shared `writeOutput` helper so `--json` keeps producing a
+ * structured envelope (id + caption + quote + meta) for scripted
+ * callers. The `--ascii-only` flag drops the box decoration in the
+ * non-JSON path so pipes (`pugi stickers --ascii-only | lolcat`) get
+ * clean plain-text frames.
+ *
+ * The same handler powers the in-REPL `/stickers` slash, which routes
+ * the text through the conversation system pane line-buffer.
+ */
+async function stickers(_args, flags, _session) {
+    runStickersCommand({
+        json: flags.json,
+        asciiOnly: flags.asciiOnly,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
+/**
+ * `pugi feedback` — Leak L21 (2026-05-27). In-CLI feedback collector.
+ *
+ * Five-step wizard:
+ *   1. category (bug / feature / general / praise)
+ *   2. rating (1-5)
+ *   3. comment (multi-line, Ctrl-D submits)
+ *   4. include redacted session context? (y/n, default n)
+ *   5. confirm submit (y/n, default y)
+ *
+ * POSTs to `<apiUrl>/api/pugi/feedback`. On transient failure (404,
+ * 5xx, network error) the envelope is appended to
+ * `<cwd>/.pugi/feedback-queue.jsonl`. On next online session the
+ * background flusher drains the queue silently.
+ *
+ * Non-TTY callers (CI, pipes) get a one-line "non-interactive — re-run
+ * in a real terminal" stub. The feedback wizard is intentionally
+ * TTY-only — scripting a star-rating + multi-line comment from a
+ * shell pipe would just produce low-signal noise.
+ */
+async function dispatchFeedback(_args, flags, _session) {
+    if (!isInteractive(flags)) {
+        writeOutput(flags, {
+            ok: false,
+            error: 'pugi feedback requires an interactive terminal. Re-run from a real TTY.',
+        }, 'pugi feedback: non-interactive shell — re-run from a real terminal.');
+        process.exitCode = 2;
+        return;
+    }
+    const { renderFeedbackPrompt } = await import('../tui/feedback-prompt.js');
+    const { runFeedbackCommand, renderFeedbackToast } = await import('./commands/feedback.js');
+    const { submitFeedback } = await import('../core/feedback/submitter.js');
+    const verdict = await renderFeedbackPrompt();
+    if (verdict.cancelled || !verdict.draft) {
+        writeOutput(flags, { ok: true, kind: 'cancelled' }, 'Feedback cancelled. Nothing was sent.');
+        return;
+    }
+    // Best-effort credential resolution. Anonymous submission is allowed
+    // (the server may still accept it for ungated `/api/pugi/feedback`
+    // routes); on no-credential we route the POST through an empty
+    // bearer + the operator gets the 4xx → "rejected" toast if the
+    // server requires auth.
+    const credential = resolveActiveCredential(process.env);
+    const apiUrl = credential?.apiUrl ?? (process.env.PUGI_API_URL || 'https://api.pugi.io');
+    const apiKey = credential?.apiKey ?? '';
+    const result = await runFeedbackCommand({
+        cwd: process.cwd(),
+        cliVersion: PUGI_CLI_VERSION,
+        submit: async (env) => submitFeedback(env, { apiUrl, apiKey }),
+        draft: verdict.draft,
+        // `pugi feedback` from a fresh shell has no live transcript — the
+        // session-context provider is omitted. The REPL slash variant
+        // wires this in via `runFeedbackSlash` (session.ts).
+    });
+    writeOutput(flags, { ok: true, result }, renderFeedbackToast(result));
+}
+/**
+ * `pugi release-notes` — Leak L24 (2026-05-27). Diff between the
+ * last-seen + installed CLI versions, rendered from the bundled
+ * `apps/pugi-cli/CHANGELOG.md`. Bumps `~/.pugi/.last-seen-version`
+ * to the installed version on every successful render so the next
+ * invocation is a no-op until the operator upgrades again.
+ *
+ * The handler stays thin: parser, slicer, and state I/O all live in
+ * `core/release-notes/`. This wrapper just hands ambient state to
+ * `runReleaseNotesCommand` so `--json` keeps producing the same
+ * envelope from both the top-level shell + the in-REPL `/release-notes`
+ * slash dispatcher.
+ *
+ * Always exits 0 — the command is informational, never a gate. Read
+ * failures, missing CHANGELOG, and write failures all degrade to a
+ * structured envelope with a human-readable footer.
+ */
+async function releaseNotes(_args, flags, _session) {
+    runReleaseNotesCommand({
+        home: defaultReleaseNotesHome(),
+        json: flags.json,
+        reset: flags.reset,
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+    });
+}
 /**
  * Programmatic init scaffolder. Idempotent — every helper call is a
  * `*_IfMissing` write, so re-running over an existing .pugi/ workspace
@@ -3844,7 +4340,7 @@ async function login(args, flags, _session) {
     if (args.includes('--help') || args.includes('-h')) {
         writeOutput(flags, {
             command: 'login',
-            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--label <name>] [--api-url <url>]',
+            usage: 'pugi login [--provider device|token|env] [--token <PAT>] [--token-stdin] [--key <value>] [--skip-validate] [--label <name>] [--api-url <url>]',
         }, [
             'Usage: pugi login [options]',
             '',
@@ -3856,19 +4352,27 @@ async function login(args, flags, _session) {
             'Non-interactive options:',
             '  --provider device   Run the device-flow login (recommended).',
             '  --provider token    Store an API key passed via --token / --token-stdin / PUGI_LOGIN_TOKEN.',
-            '  --provider env      Promote PUGI_API_KEY from the environment into the store.',
+            '  --provider env      Read PUGI_API_KEY (or --key) and verify it via /api/pugi/health.',
             '  --token <PAT>       Inline API key (visible in `ps`).',
             '  --token-stdin       Read API key from stdin (gh-CLI style).',
+            '  --key <value>       Explicit key for --provider env; beats PUGI_API_KEY.',
+            '  --skip-validate     Skip the /api/pugi/health probe for --provider env (CI bootstrap).',
             '  --label <name>      Short label surfaced in `pugi accounts list`.',
             '  --api-url <url>     Override the Anvil endpoint (self-hosted).',
             '  --no-device-flow    Refuse the device flow; fail fast in CI without a token.',
             '',
+            'Environment variables:',
+            '  PUGI_API_KEY        Read by --provider env. Pass --key to override.',
+            '  PUGI_LOGIN_TOKEN    Read by --provider token in non-interactive shells.',
+            '  PUGI_API_URL        Override the Anvil endpoint (same as --api-url).',
+            '',
             'Examples:',
             '  pugi login                                  # interactive picker on a TTY',
             '  pugi login --provider device                # explicit browser OAuth',
             '  pugi login --provider token --token sk-xx   # paste in a key',
             '  echo $TOKEN | pugi login --provider token --token-stdin',
-            '  PUGI_API_KEY=sk-xx pugi login --provider env',
+            '  PUGI_API_KEY=pugi_xxx pugi login --provider env',
+            '  pugi login --provider env --key pugi_xxx    # explicit key beats env',
         ].join('\n'));
         return;
     }
@@ -3891,6 +4395,11 @@ async function login(args, flags, _session) {
     const apiUrlOverride = extractApiUrlFlag(args);
     const labelFlag = extractLabelFlag(args);
     const provider = parseProviderFlag(args);
+    // Leak L35 (2026-05-27): `--key` is the explicit-arg path for
+    // `--provider env`; `--skip-validate` bypasses the /api/pugi/health
+    // probe (CI bootstrap before the network is up).
+    const envExplicitKey = extractKeyFlag(args);
+    const envSkipValidate = args.includes('--skip-validate');
     const apiUrl = normalizeApiUrl(apiUrlOverride ?? process.env.PUGI_API_URL ?? DEFAULT_API_URL);
     // Path 1: explicit --provider trumps everything else.
     if (provider) {
@@ -3901,6 +4410,8 @@ async function login(args, flags, _session) {
             explicitToken: tokenFromArgs,
             tokenStdinFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -3948,6 +4459,8 @@ async function login(args, flags, _session) {
             flags,
             label: labelFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -4166,16 +4679,28 @@ async function dispatchLoginProvider(provider, ctx) {
             return;
         }
         case 'env': {
-            const envKey = process.env.PUGI_API_KEY;
-            if (!envKey) {
-                throw new Error('pugi login --provider env requires PUGI_API_KEY to be exported in the current shell.');
+            // Leak L35 (2026-05-27): resolve the env / --key candidate,
+            // run the local format check, then probe `/api/pugi/health`
+            // BEFORE persisting. A bad token never lands on disk so the
+            // next `pugi <anything>` does not silently 401 against the
+            // cabinet. `--skip-validate` opts out for CI bootstrap.
+            const resolved = await resolveAndValidateEnvLogin({
+                apiUrl: ctx.apiUrl,
+                explicitKey: ctx.envExplicitKey,
+                env: process.env,
+                skipValidate: ctx.envSkipValidate ?? false,
+            });
+            if (resolved.kind !== 'ok') {
+                reportEnvLoginFailure(resolved, ctx.flags);
+                return;
             }
             storeAndAnnounceToken({
                 apiUrl: ctx.apiUrl,
-                apiKey: envKey,
+                apiKey: resolved.token,
                 label: ctx.label,
                 source: 'env',
                 flags: ctx.flags,
+                validatedLatencyMs: resolved.latencyMs > 0 ? resolved.latencyMs : undefined,
             });
             return;
         }
@@ -4194,6 +4719,15 @@ function storeAndAnnounceToken(input) {
         label: input.label,
         source: input.source,
     });
+    const textLines = [
+        `Pugi logged in for ${record.apiUrl}`,
+        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
+        `Token: ${maskApiKey(record.apiKey)}`,
+    ];
+    if (typeof input.validatedLatencyMs === 'number') {
+        textLines.push(`Verified via /api/pugi/health in ${input.validatedLatencyMs}ms`);
+    }
+    textLines.push('Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.');
     writeOutput(input.flags, {
         status: 'logged_in',
         apiUrl: record.apiUrl,
@@ -4201,12 +4735,55 @@ function storeAndAnnounceToken(input) {
         label: record.label ?? null,
         createdAt: record.createdAt,
         source: input.source,
-    }, [
-        `Pugi logged in for ${record.apiUrl}`,
-        `Method: ${input.source}${record.label ? ` (${record.label})` : ''}`,
-        `Token: ${maskApiKey(record.apiKey)}`,
-        'Stored at ~/.pugi/credentials.json (mode 0600). Run `pugi whoami` to verify.',
-    ].join('\n'));
+        ...(typeof input.validatedLatencyMs === 'number'
+            ? { validatedLatencyMs: input.validatedLatencyMs }
+            : {}),
+    }, textLines.join('\n'));
+}
+/**
+ * Render a typed `EnvLoginFailure` from `resolveAndValidateEnvLogin`
+ * onto the surrounding CLI surface. Maps the failure kind to:
+ *   - an exit code (1 by default; 2 for invalid format so a CI step
+ *     can disambiguate "missing key" vs "key shape wrong" without
+ *     parsing stderr; 4 for network / server errors so retry logic
+ *     can distinguish transient failures from credential failures)
+ *   - a structured JSON payload for `--json` consumers
+ *   - a human-readable stderr line for the interactive path
+ *
+ * The token itself is never echoed — only the validator's own message
+ * (which the env-provider module composed without the secret in it).
+ */
+function reportEnvLoginFailure(failure, flags) {
+    const exitCode = (() => {
+        switch (failure.kind) {
+            case 'missing':
+                return 1;
+            case 'invalid-format':
+                return 2;
+            case 'unauthorized':
+                return 3;
+            case 'network-error':
+            case 'server-error':
+                return 4;
+            case 'unexpected-status':
+                return 5;
+            default: {
+                const exhaustive = failure;
+                return Number(exhaustive) || 1;
+            }
+        }
+    })();
+    const payload = {
+        status: 'login_failed',
+        kind: failure.kind,
+        message: failure.message,
+    };
+    if ('status' in failure)
+        payload.httpStatus = failure.status;
+    if ('cause' in failure && failure.cause)
+        payload.cause = failure.cause;
+    writeOutput(flags, payload, failure.message);
+    process.exitCode = exitCode;
 }
 /**
  * OAuth 2.0 Device Authorization Grant client (RFC 8628). Renders
@@ -4962,6 +5539,17 @@ function extractApiUrlFlag(args) {
 function extractLabelFlag(args) {
     return extractNamedFlagValue(args, 'label');
 }
+/**
+ * `pugi login --provider env --key <value>` — explicit key arg that
+ * beats `PUGI_API_KEY` env. Same precedence rule as `gh auth login
+ * --with-token`, `aws configure set`, and `pugi config`: the most
+ * specific operator intent (a typed flag) overrides the ambient
+ * environment so an operator can override a stale `PUGI_API_KEY`
+ * from their shell rc without unsetting it first.
+ */
+function extractKeyFlag(args) {
+    return extractNamedFlagValue(args, 'key');
+}
 /**
  * `pugi jobs` — surface the persistent JobRegistry on the CLI.
  * Sprint α5.9 (ADR-0056 PR-PUGI-CLI-M1-GAP-J). Subcommand parsing