@pugi/cli 0.1.0-beta.22 → 0.1.0-beta.24

package/dist/runtime/cli.js

@@ -2,6 +2,7 @@ import { randomUUID } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { statSync } from 'node:fs';
+import { homedir } from 'node:os';
 import { dirname, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { AnvilEngineLoopClient } from '../core/engine/anvil-client.js';
@@ -22,17 +23,21 @@ 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';
@@ -104,6 +109,12 @@ const handlers = {
     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.
@@ -122,17 +133,31 @@ const handlers = {
     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
     // handler, same flags. Operators trained on Claude Code expect either
     // verb to surface the per-model token + USD table.
     usage: dispatchCost,
+    // Leak L27 (2026-05-27): `pugi update` — channel-aware npm registry
+    // probe + optional npm install shell-out. Same handler powers the
+    // in-REPL `/update` slash via the session module. R2 atomic swap
+    // deferred to Phase 2 per the sprint plan; npm is the single
+    // distribution channel today.
+    update: dispatchUpdate,
     version,
     web: dispatchWeb,
     whoami,
@@ -330,6 +355,29 @@ async function dispatchStyle(args, flags, _session) {
     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.
  *
@@ -360,6 +408,25 @@ async function dispatchOnboarding(args, flags, _session) {
     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
@@ -924,6 +991,10 @@ function parseArgs(argv) {
         // 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
@@ -1010,6 +1081,14 @@ function parseArgs(argv) {
             // 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
@@ -1368,7 +1447,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.',
@@ -1430,6 +1510,32 @@ 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.',
     ],
+    update: [
+        'pugi update — channel-aware @pugi/cli update check + install.',
+        '',
+        'Polls npm registry dist-tags for a newer @pugi/cli on the configured',
+        'channel (stable / beta / canary). Without flags, prints the install',
+        'command and exits. With --apply, shells out to `npm install -g …`.',
+        '',
+        '  --check                 Non-interactive probe + JSON envelope.',
+        '  --channel <name>        Switch channel (stable | beta | canary) and probe.',
+        '                          Persisted to ~/.pugi/config.json::updateChannel.',
+        '  --apply                 Shell out to `npm install -g @pugi/cli@<tag>`',
+        '                          after a y/n confirmation.',
+        '  --yes, -y               Skip the confirmation prompt on --apply.',
+        '  --json                  Force JSON envelope (auto-on with --check).',
+        '',
+        'Channel mapping: stable -> npm `latest`, beta -> npm `beta`,',
+        'canary -> npm `next`. Default channel is `beta` (Pugi currently',
+        'ships beta releases only).',
+        '',
+        'Also available as /update from inside the REPL — slash form NEVER',
+        'spawns npm (would corrupt the running binary); it only prints the',
+        'install command for the operator к run after exit.',
+        '',
+        'R2 atomic swap (sprint plan L27) deferred к Phase 2 — npm is the',
+        'only distribution channel today.',
+    ],
     stickers: [
         'pugi stickers — show a Pugi brand sticker (gimmick).',
         '',
@@ -1456,6 +1562,19 @@ const COMMAND_HELP_BODIES = {
         '',
         '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.',
         '',
@@ -1582,6 +1701,53 @@ async function doctor(_args, flags, _session) {
         writeOutput: (payload, text) => writeOutput(flags, payload, text),
     });
 }
+/**
+ * `pugi update` — Leak L27 (2026-05-27). Channel-aware npm registry
+ * probe + optional shell-out to `npm install -g @pugi/cli@<tag>`.
+ *
+ * Argument grammar:
+ *   pugi update                       -> probe + offer install command
+ *   pugi update --check               -> probe + JSON envelope (scripted)
+ *   pugi update --channel <name>      -> persist channel + probe
+ *   pugi update --apply [--yes]       -> probe + shell out to npm
+ *   pugi update --json                -> JSON envelope (any subcommand)
+ *
+ * The handler delegates to `runUpdateCommand` in
+ * `runtime/commands/update.ts` so the in-REPL `/update` slash + the
+ * top-level shell command share one channel-resolution + persistence
+ * + probe surface. Exit codes:
+ *
+ *   0 — happy path (no update OR update completed OR probe-only)
+ *   1 — install / probe failure with structured error
+ *   2 — argument error (unknown flag, unknown channel)
+ */
+async function dispatchUpdate(args, flags, _session) {
+    const { parseUpdateArgs, runUpdateCommand, defaultSpawnInstaller } = await import('./commands/update.js');
+    const parsed = parseUpdateArgs(args, { jsonDefault: flags.json });
+    if ('error' in parsed) {
+        writeOutput(flags, { ok: false, error: parsed.error }, parsed.error);
+        process.exitCode = 2;
+        return;
+    }
+    const envelope = await runUpdateCommand({
+        cwd: process.cwd(),
+        home: homedir(),
+        env: process.env,
+        flags: parsed,
+        promptConfirm: async (question) => {
+            const answer = await readSingleChoice(`${question} `);
+            return /^y(es)?$/i.test(answer.trim());
+        },
+        writeOutput: (payload, text) => writeOutput(flags, payload, text),
+        spawnInstaller: defaultSpawnInstaller,
+    });
+    if (!envelope.ok) {
+        // `apply_cancelled_by_operator` is a benign decline; we still
+        // surface a non-zero exit so scripted callers can detect that the
+        // operator did not green-light the install.
+        process.exitCode = 1;
+    }
+}
 /**
  * `pugi status` — Leak L34 (2026-05-27). Concise session-state probe
  * mirroring Claude Code's `/status`. Distinct from `pugi doctor`
@@ -1686,6 +1852,31 @@ async function dispatchFeedback(_args, flags, _session) {
     });
     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
@@ -4229,7 +4420,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]',
             '',
@@ -4241,19 +4432,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;
     }
@@ -4276,6 +4475,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) {
@@ -4286,6 +4490,8 @@ async function login(args, flags, _session) {
             explicitToken: tokenFromArgs,
             tokenStdinFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -4333,6 +4539,8 @@ async function login(args, flags, _session) {
             flags,
             label: labelFlag,
             noDeviceFlow,
+            envExplicitKey,
+            envSkipValidate,
         });
         return;
     }
@@ -4551,16 +4759,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;
         }
@@ -4579,6 +4799,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,
@@ -4586,12 +4815,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
@@ -5347,6 +5619,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

package/dist/runtime/commands/doctor.js

@@ -50,6 +50,7 @@ import { probeConfig } from '../../core/diagnostics/probes/config.js';
 import { probeSession } from '../../core/diagnostics/probes/session.js';
 import { probeDenialTracking } from '../../core/diagnostics/probes/denial-tracking.js';
 import { probeBareMode } from '../../core/diagnostics/probes/bare-mode.js';
+import { probePugiMdHierarchy } from '../../core/diagnostics/probes/pugi-md.js';
 /**
  * Default API URL when no PUGI_API_URL env override is set. Mirrors
  * the constant in `core/credentials.ts` (kept local to avoid an
@@ -214,6 +215,18 @@ export function buildDefaultProbes(ctx, options = {}) {
             name: 'BARE MODE',
             run: async () => probeBareMode({ env: ctx.env }),
         },
+        // Leak L32 (2026-05-27): PUGI.md HIERARCHY row. Reports how many
+        // ambient `PUGI.md` / `CLAUDE.md` files the cwd → homedir walk
+        // discovered, and the closest path. `skipped` when bare mode is
+        // active (walk disabled) or zero files found.
+        {
+            name: 'PUGI.md HIERARCHY',
+            run: async () => probePugiMdHierarchy({
+                cwd: ctx.cwd,
+                homedir: ctx.home,
+                env: ctx.env,
+            }),
+        },
     ];
     return probes;
 }