@pugi/cli 0.1.0-beta.89 → 0.1.0-beta.90

package/dist/core/edits/dispatch.js

@@ -47,6 +47,7 @@ import { spawnSync } from 'node:child_process';
 import { readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { resolve, sep } from 'node:path';
 import { commitCheckpoint, formatCheckpointMessage, initShadowRepo, ShadowGitUnavailableError, } from '../checkpoints/shadow-git.js';
+import { detectEditFormat } from './format-detector.js';
 import { LayerDDeferredError, applyLayerD } from './layer-d-ast.js';
 import { applyLayerA } from './layer-a-apply.js';
 import { applyLayerAFuzzy } from './layer-a-fuzzy-apply.js';
@@ -62,6 +63,15 @@ import { appendEntry, snapshotForDispatch, } from './journal.js';
  */
 export async function dispatchEdit(raw, opts) {
     const family = resolveFamily(opts.modelTag);
+    // PUGI-79 — resolve the preferred-layer chain ONCE per dispatch.
+    // Caller supplied wins; otherwise the detector derives from modelTag.
+    // The chain is informational here (the parser still routes per
+    // envelope); a future fuzzy-ladder change can read it to influence
+    // retry ordering without revisiting the dispatcher's escalation
+    // contract.
+    const preferredChain = resolvePreferredChain(opts);
+    if (preferredChain)
+        opts.onPreferredLayer?.(preferredChain);
     let parsed;
     try {
         parsed = parseMarkers(raw, family);
@@ -75,6 +85,7 @@ export async function dispatchEdit(raw, opts) {
                 bytesWritten: 0,
                 reason: 'marker_parse_error',
                 detail: `${error.message}${error.atLine ? ` (line ${error.atLine})` : ''} — modelHint=${error.modelHint}`,
+                ...(preferredChain ? { expectedLayer: preferredChain.primary } : {}),
             };
             opts.onResult?.(result);
             return [result];
@@ -141,6 +152,7 @@ export async function dispatchEdit(raw, opts) {
             opts.checkpoint.onCheckpointError?.(err, '');
         }
     }
+    const expectedLayer = preferredChain?.primary;
     const out = [];
     let crashError = null;
     for (const edit of parsed) {
@@ -166,6 +178,13 @@ export async function dispatchEdit(raw, opts) {
                 detail: `dispatch threw: ${msg}`,
             };
         }
+        if (expectedLayer !== undefined) {
+            // PUGI-79: stamp the expected layer on every result so
+            // observability surfaces can compute drift (expected vs actual)
+            // per family. The actual `layer` field is unchanged — the
+            // hint is informational, not a routing override.
+            result = { ...result, expectedLayer };
+        }
         out.push(result);
         opts.onResult?.(result);
         if (result.ok && checkpointEnabled && opts.checkpoint && !opts.dryRun) {
@@ -339,6 +358,27 @@ function listTrackedFiles(cwd, paths) {
     }
     return out;
 }
+/**
+ * PUGI-79 helper — resolve the preferred-layer chain for this
+ * dispatch. Caller-supplied `preferredLayer` wins; otherwise the
+ * detector derives from `modelTag`. Returns null when neither path
+ * yields a chain (no caller hint AND no model tag) — the dispatcher
+ * skips the observability hook in that case so we do not emit a
+ * misleading wildcard reading.
+ */
+function resolvePreferredChain(opts) {
+    if (opts.preferredLayer) {
+        // Defensive clone so caller mutations after dispatchEdit returns
+        // cannot poison subsequent calls that share the chain reference.
+        return {
+            primary: opts.preferredLayer.primary,
+            fallback: [...opts.preferredLayer.fallback],
+        };
+    }
+    if (opts.modelTag)
+        return detectEditFormat(opts.modelTag);
+    return null;
+}
 /**
  * Public helper exposed for the marker parser tests + CLI surface that
  * may want to know the resolved family without re-running the auto

package/dist/core/edits/format-detector.js

@@ -0,0 +1,260 @@
+/**
+ * Edit-format auto-select (PUGI-79).
+ *
+ * The 4-layer diff dispatcher (Layer A single-block, B ordered batch,
+ * C sha256-gated rewrite, D AST-aware) is layer-agnostic at the wire
+ * — the model emits whichever marker family it was prompted with, and
+ * `dispatch.ts` routes per envelope. Empirically though, different
+ * model families have markedly different success rates per layer:
+ *
+ *   - Anthropic Claude family — native function-calling shape;
+ *     produces clean single-block Layer A edits with high recall
+ *     against `+++ NEW / --- OLD / ===` markers.
+ *   - Open-weight Qwen3 / Kimi / DeepSeek — historically stronger
+ *     with whole-file Layer C rewrites OR sha256-gated patches; the
+ *     conflict-marker (Gemini-style) Layer A surface has higher
+ *     ambiguity rates on these models.
+ *   - DeepSeek-coder family — anchors well on Layer C primary with
+ *     Layer A as fallback (their RLHF set leaned hard on patch-style
+ *     emit).
+ *   - Reasoning models (o-series, gpt-5) — handle Layer D AST-aware
+ *     operations when an LSP bridge is available; Layer C primary
+ *     otherwise.
+ *
+ * The existing `format-matrix.ts` keyed exact slugs only — fine for
+ * the canonical set but blind to vendor-prefixed slugs that come back
+ * from the Anvil gateway (e.g. `anthropic/claude-sonnet-4-20250514`,
+ * `qwen/qwen3-coder`, `deepseek/deepseek-chat-v3.1`). This detector
+ * layers ON TOP of the matrix:
+ *
+ *   1. exact-key match against `EDIT_FORMAT_MATRIX` — wins outright.
+ *   2. vendor-prefix strip → second exact-key probe (so
+ *      `anthropic/claude-sonnet-4-6` resolves the same as `claude-sonnet-4-6`).
+ *   3. family inference from the (possibly prefixed) slug — returns
+ *      the family-default chain (see `FAMILY_DEFAULTS`).
+ *   4. unknown — wildcard `*` from the matrix.
+ *
+ * The output is the same `EditFormatChain` shape the matrix already
+ * exposes so callers (dispatcher hint, persona prompt hint) consume a
+ * single contract.
+ *
+ * NOT a routing decision: the dispatcher's per-layer routing is still
+ * driven by what the model actually emits. The detector's output is a
+ * HINT — surfaced to the persona prompt so the model has the right
+ * marker template loaded, and surfaced to the dispatcher's fuzzy ladder
+ * / fallback ordering so an ambiguous response gets retried in an order
+ * that matches the model's empirical strengths.
+ *
+ * Spec: this is the PUGI-79 implementation; the issue ships the
+ * detector + dispatcher hint + persona hint together.
+ */
+import { EDIT_FORMAT_MATRIX, } from './format-matrix.js';
+/**
+ * Family-level default chains. These are deliberately CONSERVATIVE —
+ * each family's primary is the layer with the highest observed apply-
+ * rate across the 2026-05 dogfood corpus; fallbacks rank in observed
+ * success order. The exact-slug entries in `EDIT_FORMAT_MATRIX` can
+ * override per-model; family defaults are the floor.
+ *
+ * Anthropic:
+ *   The Anvil corpus shows Claude family hitting ~95% Layer A apply on
+ *   first try; Layer C is the rescue when the file is large enough
+ *   that the operator's region selection ambiguates. Matrix entries
+ *   for `claude-opus-4-7` + `claude-sonnet-4-6` override to Layer C
+ *   primary because the larger context windows let those models hold
+ *   the whole file comfortably.
+ *
+ * Open-weight (qwen / deepseek / kimi):
+ *   These ship whole-file rewrites more reliably than partial diffs —
+ *   the patch-style envelopes their fine-tune sets prefer match Layer
+ *   C semantics. Layer A is the fallback because they can still emit
+ *   sensible search/replace pairs when prompted explicitly.
+ *
+ * Reasoning (gpt-5 / o-series):
+ *   Layer C primary because the longer reasoning trace burns through
+ *   the partial-diff format's positional constraints. Layer D rides
+ *   the wire when an LSP is bridged; the matrix entries override per-
+ *   model when that's available (see `qwen3-coder-480b → D`).
+ *
+ * Unknown:
+ *   Defers to the wildcard chain from the matrix (Layer A primary).
+ */
+const FAMILY_DEFAULTS = {
+    anthropic: { primary: 'A', fallback: ['C', 'B'] },
+    openai: { primary: 'C', fallback: ['A', 'B'] },
+    gemini: { primary: 'A', fallback: ['C', 'B'] },
+    qwen: { primary: 'A', fallback: ['C', 'B'] },
+    deepseek: { primary: 'C', fallback: ['A', 'B'] },
+    kimi: { primary: 'C', fallback: ['A', 'B'] },
+    unknown: { primary: 'A', fallback: ['B', 'C'] },
+};
+/**
+ * Detect the model family from a slug. Handles vendor-prefixed forms
+ * (`<vendor>/<model>` and `<provider>:<model>`) plus bare-name forms.
+ * Case-insensitive on the family name; case-preserving on the rest.
+ *
+ * Order matters: vendor prefix wins when present (the gateway is
+ * authoritative about which family routed). Otherwise the bare slug
+ * gets prefix-matched against well-known family stems. Unknown slugs
+ * surface as `unknown` — the caller falls back to the matrix wildcard.
+ */
+export function detectModelFamily(modelSlug) {
+    if (!modelSlug)
+        return 'unknown';
+    const raw = modelSlug.trim();
+    if (raw.length === 0)
+        return 'unknown';
+    const lower = raw.toLowerCase();
+    // Vendor-prefix form: `<vendor>/<model>`. The vendor wins outright
+    // because the gateway is authoritative — `anthropic/<anything>`
+    // routes Claude family regardless of the suffix.
+    const slashIdx = lower.indexOf('/');
+    if (slashIdx > 0) {
+        const vendor = lower.slice(0, slashIdx);
+        switch (vendor) {
+            case 'anthropic':
+                return 'anthropic';
+            case 'openai':
+                return 'openai';
+            case 'google':
+            case 'gemini':
+            case 'xai':
+                return 'gemini';
+            case 'qwen':
+            case 'alibaba':
+                return 'qwen';
+            case 'deepseek':
+                return 'deepseek';
+            case 'moonshot':
+            case 'kimi':
+                return 'kimi';
+            default:
+                // Unknown vendor — fall through to bare-name detection on the
+                // suffix. Some gateways (OpenRouter style) put the family
+                // name AFTER the vendor (e.g. `together/qwen-coder`), so the
+                // suffix still carries signal.
+                return detectFamilyFromBareName(lower.slice(slashIdx + 1));
+        }
+    }
+    // Provider-prefix form: `ollama:<model>` (engine-VM local runtime).
+    // The prefix is informational; strip and continue.
+    const colonIdx = lower.indexOf(':');
+    if (colonIdx > 0) {
+        const prefix = lower.slice(0, colonIdx);
+        if (prefix === 'ollama' || prefix === 'lmstudio' || prefix === 'llama-cpp') {
+            return detectFamilyFromBareName(lower.slice(colonIdx + 1));
+        }
+    }
+    return detectFamilyFromBareName(lower);
+}
+/**
+ * Bare-name detector. Lower-case input. Prefix-match against family
+ * stems; longest match wins so `claude-opus-4-7` doesn't accidentally
+ * route through the generic `c*` lane.
+ */
+function detectFamilyFromBareName(name) {
+    if (name.startsWith('claude'))
+        return 'anthropic';
+    if (name.startsWith('gpt') || name.startsWith('o1') || name.startsWith('o3') || name.startsWith('o4')) {
+        return 'openai';
+    }
+    if (name.startsWith('gemini') || name.startsWith('grok'))
+        return 'gemini';
+    if (name.startsWith('qwen'))
+        return 'qwen';
+    if (name.startsWith('deepseek'))
+        return 'deepseek';
+    if (name.startsWith('kimi') || name.startsWith('moonshot'))
+        return 'kimi';
+    return 'unknown';
+}
+/**
+ * Family-default chain. Exported for callers that want the family-
+ * level recommendation without running the full detector pipeline
+ * (e.g. observability surfaces that already resolved the family).
+ */
+export function familyDefaultChain(family) {
+    // Defensive clone: the FAMILY_DEFAULTS table is readonly conceptually
+    // but the EditFormatChain type allows fallback array mutation. Clone
+    // so callers cannot accidentally mutate the table.
+    const base = FAMILY_DEFAULTS[family];
+    return { primary: base.primary, fallback: [...base.fallback] };
+}
+/**
+ * Resolve the preferred edit-format chain for a model slug.
+ *
+ * Resolution order:
+ *   1. Exact slug match in EDIT_FORMAT_MATRIX — overrides everything.
+ *      This lets per-model tuning (e.g. `qwen3-coder-480b → D`) win
+ *      over the family default.
+ *   2. Vendor-prefix strip + exact match — so `anthropic/claude-...`
+ *      resolves to the bare `claude-...` entry when present.
+ *   3. Family inference — `FAMILY_DEFAULTS[detectModelFamily(slug)]`.
+ *   4. Wildcard fallback — `EDIT_FORMAT_MATRIX['*']`.
+ *
+ * The returned chain is always a fresh object so caller mutations
+ * cannot leak back into the matrix.
+ */
+export function detectEditFormat(modelSlug) {
+    const fallbackWildcard = EDIT_FORMAT_MATRIX['*'] ?? { primary: 'A', fallback: [] };
+    if (!modelSlug || modelSlug.trim().length === 0) {
+        return { primary: fallbackWildcard.primary, fallback: [...fallbackWildcard.fallback] };
+    }
+    const raw = modelSlug.trim();
+    // Step 1 — exact match wins.
+    const exact = EDIT_FORMAT_MATRIX[raw];
+    if (exact)
+        return { primary: exact.primary, fallback: [...exact.fallback] };
+    // Step 2 — vendor-prefix strip (e.g. `anthropic/claude-sonnet-4-6`).
+    const slashIdx = raw.indexOf('/');
+    if (slashIdx > 0) {
+        const suffix = raw.slice(slashIdx + 1);
+        const stripped = EDIT_FORMAT_MATRIX[suffix];
+        if (stripped)
+            return { primary: stripped.primary, fallback: [...stripped.fallback] };
+    }
+    // Step 3 — family inference.
+    const family = detectModelFamily(raw);
+    if (family !== 'unknown')
+        return familyDefaultChain(family);
+    // Step 4 — wildcard.
+    return { primary: fallbackWildcard.primary, fallback: [...fallbackWildcard.fallback] };
+}
+/**
+ * Render a one-line marker-format hint for the persona prompt. The
+ * dispatcher already accepts every marker family (anthropic / gemini /
+ * openai), so the hint is preference, not gating — surface the
+ * preferred template + alternative so the model knows which envelope
+ * has the highest apply-rate for its family.
+ *
+ * Returns `null` when the slug is unknown / unset; the caller drops
+ * the hint module on null so the prompt is not polluted with empty
+ * sections.
+ */
+export function renderEditFormatHint(modelSlug) {
+    if (!modelSlug || modelSlug.trim().length === 0)
+        return null;
+    const family = detectModelFamily(modelSlug);
+    if (family === 'unknown')
+        return null;
+    const chain = detectEditFormat(modelSlug);
+    const markerStyle = FAMILY_MARKER_TEMPLATE[family];
+    return `# Edit-format hint (auto-selected for ${family})
+Preferred layer: Layer ${chain.primary}${chain.fallback.length > 0 ? ` (fallback: ${chain.fallback.map((l) => `Layer ${l}`).join(' -> ')})` : ''}.
+Marker template: ${markerStyle}
+The dispatcher accepts any marker family; this hint optimises apply-rate for the resolved model.`;
+}
+/**
+ * Marker template literal per family. Mirrors the three envelopes the
+ * marker-parser accepts; used by `renderEditFormatHint` so the model
+ * sees a concrete shape next to the layer recommendation.
+ */
+const FAMILY_MARKER_TEMPLATE = {
+    anthropic: '+++ NEW <file> / <new contents> / --- OLD <file> / <old contents> / ===',
+    openai: '@@@ REWRITE <file> sha256=<hex> / <full new contents> / @@@ END',
+    gemini: '<<<<<<< SEARCH <file> / <old> / ======= / <new> / >>>>>>> REPLACE',
+    qwen: '<<<<<<< SEARCH <file> / <old> / ======= / <new> / >>>>>>> REPLACE',
+    deepseek: '@@@ REWRITE <file> sha256=<hex> / <full new contents> / @@@ END',
+    kimi: '@@@ REWRITE <file> sha256=<hex> / <full new contents> / @@@ END',
+};
+//# sourceMappingURL=format-detector.js.map

package/dist/core/edits/index.js

@@ -14,4 +14,6 @@ export { applyLayerC, sha256OfUtf8, } from './layer-c-apply.js';
 export { applyLayerD, LayerDDeferredError, } from './layer-d-ast.js';
 export { MarkerParseError, detectFamily, parseMarkers, } from './marker-parser.js';
 export { dispatchEdit, resolveFamily, } from './dispatch.js';
+export { EDIT_FORMAT_MATRIX, pickEditFormat, } from './format-matrix.js';
+export { detectEditFormat, detectModelFamily, familyDefaultChain, renderEditFormatHint, } from './format-detector.js';
 //# sourceMappingURL=index.js.map

package/dist/runtime/cli.js

@@ -1801,6 +1801,11 @@ function parseArgs(argv) {
             ? process.env.PUGI_HIDE_TOOL_STREAM === '1'
             : true,
         noDefaults: process.env.PUGI_INIT_NO_DEFAULTS === '1',
+        // #82 — opt-out for the codebase scan + PUGI.md auto-gen step that
+        // runs as part of `pugi init`. Default OFF (scan runs); env var
+        // PUGI_INIT_NO_SCAN=1 lets wrappers force-disable globally without
+        // editing every invocation.
+        noScan: process.env.PUGI_INIT_NO_SCAN === '1',
         // UX : auto-init / auto-login opt-outs. Default
         // OFF (auto-init + auto-login are on by default on an interactive
         // TTY). PUGI_NO_AUTO_* env vars provide a per-shell escape hatch
@@ -1930,6 +1935,19 @@ function parseArgs(argv) {
             // at the global level for consistency with --no-splash / --no-tool-stream.
             flags.noDefaults = true;
         }
+        else if (arg === '--no-scan') {
+            // #82 init-only flag: skip the codebase scan + PUGI.md auto-gen.
+            // Parsed globally for symmetry with the other init opt-outs.
+            flags.noScan = true;
+        }
+        else if (arg === '--scan') {
+            // #82 init-only flag: explicit opt-in for the codebase scan.
+            // Scan is on by default, so this is a no-op alias kept for
+            // documentation / discoverability via `--help`. The flip exists
+            // so a wrapper that previously exported PUGI_INIT_NO_SCAN=1 can
+            // re-enable scanning per-invocation without unsetting the env.
+            flags.noScan = false;
+        }
         else if (arg === '--live') {
             flags.live = true;
         }
@@ -2285,13 +2303,20 @@ const COMMAND_HELP_BODIES = {
         'pugi init — bootstrap a new Pugi workspace in the current directory.',
         '',
         'Creates .pugi/{PUGI.md, mcp.json, index.json, artifacts/, sessions/} and',
-        'seeds the 6 default skills. Idempotent — running again only fills gaps.',
+        'seeds the 6 default skills. After scaffolding, scans the codebase and',
+        'auto-generates a project-aware PUGI.md (stack, frameworks, commands,',
+        'layout). Idempotent — running again only fills gaps.',
         '',
         'Flags:',
         ' --no-defaults    Skip the bundled default-skills install.',
+        ' --scan           Run the codebase scan + PUGI.md auto-gen (default).',
+        ' --no-scan        Skip the codebase scan + PUGI.md auto-gen.',
+        ' --force          Overwrite an existing PUGI.md when scanning.',
+        ' --style=<tier>   PUGI.md verbosity: minimal | standard | detailed.',
         '',
         'Env:',
         ' PUGI_INIT_NO_DEFAULTS=1  Same as --no-defaults.',
+        ' PUGI_INIT_NO_SCAN=1      Same as --no-scan.',
     ],
     explain: [
         'pugi explain "<question>" — read-only Q&A about the workspace.',
@@ -2710,6 +2735,8 @@ 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.',
+        ' --no-scan              Skip codebase scan + PUGI.md auto-gen on',
+        '                         `pugi init`. Pairs with PUGI_INIT_NO_SCAN=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.',
@@ -3170,7 +3197,10 @@ async function init(args, flags, _session) {
     // auto-generate PUGI.md. The runner writes its own envelope/output so
     // the standalone summary stays compact. `--json` mode collects the
     // envelope and merges it into the init payload instead of double-emitting.
-    const initScanArgs = args.filter((a) => a !== '--no-defaults');
+    // The scan is opt-out via `--no-scan` / PUGI_INIT_NO_SCAN=1 — keeps
+    // the scaffold half of `pugi init` working in CI fixtures that should
+    // not write a PUGI.md sibling to the workspace root.
+    const initScanArgs = args.filter((a) => a !== '--no-defaults' && a !== '--no-scan' && a !== '--scan');
     const style = parseInitStyle(initScanArgs);
     const useYes = args.includes('--yes') || args.includes('-y') || flags.json;
     const force = args.includes('--force');
@@ -3185,22 +3215,30 @@ async function init(args, flags, _session) {
                 scanLines.push(` ${line}`);
         }
     };
-    try {
-        scanEnvelope = await runInitScanCommand(initScanArgs, {
-            cwd,
-            force,
-            style,
-            yes: useYes,
-            json: flags.json,
-            writeOutput: captureWriteOutput,
-        });
+    if (flags.noScan) {
+        if (!flags.json) {
+            scanLines.push('');
+            scanLines.push('PUGI.md scan: skipped (--no-scan)');
+        }
     }
-    catch (error) {
-        // Init scan failure must NOT break the scaffold step. Surface a
-        // single warning line so the operator can re-run `pugi init` later.
-        const message = error instanceof Error ? error.message : String(error);
-        scanLines.push('');
-        scanLines.push(`PUGI.md scan failed: ${message}`);
+    else {
+        try {
+            scanEnvelope = await runInitScanCommand(initScanArgs, {
+                cwd,
+                force,
+                style,
+                yes: useYes,
+                json: flags.json,
+                writeOutput: captureWriteOutput,
+            });
+        }
+        catch (error) {
+            // Init scan failure must NOT break the scaffold step. Surface a
+            // single warning line so the operator can re-run `pugi init` later.
+            const message = error instanceof Error ? error.message : String(error);
+            scanLines.push('');
+            scanLines.push(`PUGI.md scan failed: ${message}`);
+        }
     }
     writeOutput(flags, { ...result, codegraph: codegraphLines.envelope, pugiMd: scanEnvelope }, [
         'Pugi initialized',

package/dist/runtime/version.js

@@ -44,7 +44,7 @@ export function sanitizeSemver(raw) {
  * during import). When bumping the CLI version BOTH literals must be
  * updated; the release smoke-test (`pack:smoke`) verifies they agree.
  */
-export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.89');
+export const PUGI_CLI_VERSION = sanitizeSemver('0.1.0-beta.90');
 /**
  * Outbound: the CLI's installed semver. Read at request time by
  * `version-interceptor.ts` and injected on every `fetch` call.

package/dist/tools/ask-user-question.js

@@ -48,6 +48,23 @@ export const ASK_USER_QUESTION_OPTION_DESC_MAX = 200;
 /** Option count: 2-4 strict. UI adds "Other" automatically. */
 export const ASK_USER_QUESTION_OPTIONS_MIN = 2;
 export const ASK_USER_QUESTION_OPTIONS_MAX = 4;
+/**
+ * Preview pane cap (PUGI-130). Lets the model attach a multi-line
+ * ASCII / code / diagram preview to an option. When ANY option в a
+ * single-select question carries `preview`, the UI switches к
+ * side-by-side layout (options column left, preview pane right).
+ *
+ * Capped at 5000 chars так что a single payload can stash a full
+ * component sketch / SQL migration / diagram, but не enough rope для
+ * a model to dump the entire codebase в a preview field.
+ *
+ * **multiSelect rule:** previews are REJECTED on multi-select questions.
+ * Rendering N preview panes simultaneously breaks the layout invariant
+ * (single 80-col terminal can host ONE side panel, not N). The schema
+ * validator enforces this at the tool boundary с a clear error message.
+ */
+export const ASK_USER_QUESTION_OPTION_PREVIEW_MIN = 1;
+export const ASK_USER_QUESTION_OPTION_PREVIEW_MAX = 5000;
 /** PUGI-480 short-format chip rules: ≤ 5 words / option label, ≤ 3 questions / call. */
 export const ASK_USER_QUESTION_CHIP_LABEL_WORD_MAX = 5;
 export const ASK_USER_QUESTION_CHIPS_MAX = 3;
@@ -83,15 +100,18 @@ export const askUserQuestionOptionSchema = z.strictObject({
         .describe('What this option means / implications.'),
     preview: z
         .string()
-        .min(1)
-        .max(2000)
+        .min(ASK_USER_QUESTION_OPTION_PREVIEW_MIN)
+        .max(ASK_USER_QUESTION_OPTION_PREVIEW_MAX)
         .optional()
-        .describe('Optional ASCII / code preview. When ANY option in the set carries ' +
-        'this field, the UI switches к side-by-side layout (options column ' +
-        'left, preview pane right). Use для visual comparison of mockups, ' +
-        'config snippets, diagram variations.'),
+        .describe('Optional ASCII / code preview (≤ 5000 chars, multi-line OK). When ' +
+        'ANY option in the set carries this field, the UI switches к ' +
+        'side-by-side layout (options column left, preview pane right). ' +
+        'Use для visual comparison of mockups, config snippets, diagram ' +
+        'variations. REJECTED on multiSelect questions (one pane fits one ' +
+        'preview).'),
 });
-export const askUserQuestionSchema = z.strictObject({
+export const askUserQuestionSchema = z
+    .strictObject({
     question: z
         .string()
         .min(ASK_USER_QUESTION_MIN)
@@ -115,6 +135,26 @@ export const askUserQuestionSchema = z.strictObject({
         .optional()
         .default(false)
         .describe('Allow multiple selections. Default false.'),
+})
+    .superRefine((payload, ctx) => {
+    // PUGI-130 invariant: previews are single-pane only. Side-by-side
+    // layout can host ONE preview at a time; multiSelect implies the
+    // operator may toggle several options and each would want its own
+    // pane. Reject at the schema boundary so the model gets immediate
+    // feedback instead of a silently dropped preview field at render.
+    if (payload.multiSelect === true) {
+        payload.options.forEach((opt, idx) => {
+            if (typeof opt.preview === 'string' && opt.preview.length > 0) {
+                ctx.addIssue({
+                    code: z.ZodIssueCode.custom,
+                    path: ['options', idx, 'preview'],
+                    message: 'preview is not allowed on multiSelect questions — ' +
+                        'side-by-side layout supports ONE preview pane at a time. ' +
+                        'Drop the preview field OR switch к single-select.',
+                });
+            }
+        });
+    }
 });
 /**
  * PUGI-480 multi-question chip payload — a bundle of up to 3 short-format
@@ -275,13 +315,22 @@ export const askUserQuestionJsonSchema = {
                         maxLength: ASK_USER_QUESTION_OPTION_DESC_MAX,
                         description: 'What this option means / implications.',
                     },
+                    preview: {
+                        type: 'string',
+                        minLength: ASK_USER_QUESTION_OPTION_PREVIEW_MIN,
+                        maxLength: ASK_USER_QUESTION_OPTION_PREVIEW_MAX,
+                        description: 'Optional multi-line ASCII / code / diagram preview (≤ 5000 chars). ' +
+                            'When ANY option carries this, UI switches к side-by-side layout. ' +
+                            'Single-select only — REJECTED if multiSelect is true.',
+                    },
                 },
             },
             description: '2-4 mutually-exclusive options. NEVER add "Other" — UI auto-adds.',
         },
         multiSelect: {
             type: 'boolean',
-            description: 'Allow multiple selections. Default false.',
+            description: 'Allow multiple selections. Default false. When true, option.preview ' +
+                'is forbidden (one terminal pane fits one preview at a time).',
         },
     },
 };

package/dist/tui/ask-user-question-chips.js

@@ -58,6 +58,39 @@ export const ASK_CHIPS_LABEL_WORD_CAP = 5;
 export const ASK_CHIPS_LABEL_CHAR_CAP = 22;
 export const ASK_CHIPS_QUESTION_CAP = 3;
 export const ASK_CHIPS_SKIP_LABEL = 'Skip — use defaults';
+/**
+ * PUGI-130 preview pane width (columns). Sized for a default 80-col
+ * terminal: option column ≈ 32, preview pane ≈ 44 with 4 gutters/borders.
+ * The pane wraps long lines defensively but the schema-level 5000-char
+ * cap is the primary guard against runaway payloads.
+ */
+export const ASK_CHIPS_PREVIEW_PANE_WIDTH = 44;
+/**
+ * Defensive char cap applied at render time. Schema enforces 5000 chars
+ * at the tool boundary; renderer mirrors the cap so a legacy / malformed
+ * payload sneaking past Zod still cannot exhaust the terminal scrollback.
+ */
+export const ASK_CHIPS_PREVIEW_CHAR_CAP = 5000;
+/**
+ * True if ANY option в ANY question of the bundle carries a non-empty
+ * `preview` field. The renderer uses this gate to switch к side-by-side
+ * layout (vertical option list + preview pane). When false, the legacy
+ * horizontal chip layout is preserved (zero regression for callers
+ * shipping previewless payloads — PR #851 contract intact).
+ */
+export function hasAnyPreview(questions) {
+    return questions.some((q) => q.options.some((opt) => typeof opt.preview === 'string' && opt.preview.length > 0));
+}
+/**
+ * Defensive char cap on preview content. Schema enforces 5000 chars at
+ * the tool boundary; we mirror the cap here so legacy / malformed
+ * payloads slipping past Zod still cannot exhaust the terminal.
+ */
+export function clampPreview(raw) {
+    if (raw.length <= ASK_CHIPS_PREVIEW_CHAR_CAP)
+        return raw;
+    return `${raw.slice(0, ASK_CHIPS_PREVIEW_CHAR_CAP - 1)}…`;
+}
 /**
  * Truncate a label к the configured word / character caps. Always
  * append "…" when truncation happens so the operator knows the chip
@@ -219,6 +252,31 @@ export function AskUserQuestionChips(props) {
         return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsx(Text, { bold: true, children: `Pugi: ${questions.length} quick ${questions.length === 1 ? 'choice' : 'choices'}` }) }), questions.map((q, qIdx) => (_jsxs(Box, { flexDirection: "column", marginTop: 1, children: [_jsx(Text, { bold: true, color: "cyan", children: `${q.header}` }), q.options.map((opt, oIdx) => (_jsx(Text, { children: `  ${oIdx + 1}. ${truncateLabel(opt.label)}${oIdx === 0 ? ' (default)' : ''}` }, `q-${qIdx}-o-${oIdx}`)))] }, `q-${qIdx}-${q.header}`))), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, italic: true, children: `(non-interactive — defaults apply)` }) })] }));
     }
     // ─── Interactive Ink render ─────────────────────────────────────────
+    // PUGI-130: when ANY option carries `preview`, switch layout — chips
+    // stack vertically (option list) and a preview pane mounts on the
+    // right, updating as the cursor moves. Otherwise fall back to the
+    // existing horizontal chip layout (zero-regression contract).
+    const previewMode = hasAnyPreview(questions);
+    if (previewMode) {
+        const focusedQ = questions[focusedQuestion];
+        const focusedCursor = cursorPerQuestion[focusedQuestion] ?? 0;
+        const focusedOpt = focusedQ?.options[focusedCursor];
+        const rawPreview = focusedOpt?.preview ?? '';
+        const previewText = clampPreview(rawPreview);
+        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsx(Text, { bold: true, children: `Pugi: ${questions.length} quick ${questions.length === 1 ? 'choice' : 'choices'}` }) }), _jsxs(Box, { flexDirection: "row", marginTop: 1, children: [_jsx(Box, { flexDirection: "column", marginRight: 2, children: questions.map((q, qIdx) => {
+                                const isFocused = qIdx === focusedQuestion;
+                                const cursor = cursorPerQuestion[qIdx] ?? 0;
+                                const isSkipped = skipped[qIdx] === true;
+                                return (_jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: isFocused ? 'cyan' : 'gray', paddingX: 1, marginBottom: qIdx < questions.length - 1 ? 1 : 0, minWidth: 28, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, color: isFocused ? 'cyan' : undefined, children: q.header }), isSkipped ? (_jsx(Text, { dimColor: true, italic: true, children: ' (skipped)' })) : null] }), q.options.map((opt, oIdx) => {
+                                            const isHighlighted = isFocused && oIdx === cursor;
+                                            const label = truncateLabel(opt.label);
+                                            const isSkipOption = label === ASK_CHIPS_SKIP_LABEL ||
+                                                opt.label === ASK_CHIPS_SKIP_LABEL;
+                                            const hasPreview = typeof opt.preview === 'string' && opt.preview.length > 0;
+                                            return (_jsxs(Box, { children: [_jsx(Text, { color: isHighlighted ? 'cyan' : undefined, bold: isHighlighted, children: isHighlighted ? '▸ ' : '  ' }), _jsx(Text, { color: isHighlighted ? 'cyan' : undefined, children: `${oIdx + 1} ` }), isSkipOption ? (_jsx(Text, { dimColor: true, italic: true, children: label })) : (_jsx(Text, { bold: isHighlighted, children: label })), hasPreview ? (_jsx(Text, { dimColor: true, children: ' ⊕' })) : null] }, `opt-${qIdx}-${oIdx}-${opt.label}`));
+                                        })] }, `chip-${qIdx}-${q.header}`));
+                            }) }), _jsxs(Box, { flexDirection: "column", borderStyle: "single", borderColor: "gray", paddingX: 1, minWidth: ASK_CHIPS_PREVIEW_PANE_WIDTH, flexGrow: 1, children: [_jsxs(Box, { children: [_jsx(Text, { bold: true, dimColor: true, children: 'Preview' }), focusedOpt ? (_jsx(Text, { dimColor: true, children: ` · ${truncateLabel(focusedOpt.label)}` })) : null] }), previewText.length > 0 ? (previewText.split('\n').map((line, lineIdx) => (_jsx(Text, { children: line.length > 0 ? line : ' ' }, `pv-${focusedQuestion}-${focusedCursor}-${lineIdx}`)))) : (_jsx(Text, { dimColor: true, italic: true, children: '(no preview for this option)' }))] })] }), _jsx(Box, { marginTop: 1, children: _jsx(Text, { dimColor: true, children: `[Enter] use highlighted defaults  ·  [↑↓] navigate  ·  [←→] switch  ·  [s] skip  ·  [Esc] cancel` }) })] }));
+    }
     return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { children: _jsx(Text, { bold: true, children: `Pugi: ${questions.length} quick ${questions.length === 1 ? 'choice' : 'choices'}` }) }), _jsx(Box, { flexDirection: "row", marginTop: 1, children: questions.map((q, qIdx) => {
                     const isFocused = qIdx === focusedQuestion;
                     const cursor = cursorPerQuestion[qIdx] ?? 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pugi/cli",
-  "version": "0.1.0-beta.89",
+  "version": "0.1.0-beta.90",
   "description": "Pugi CLI - terminal-native software execution system",
   "homepage": "https://pugi.io",
   "repository": {
@@ -63,7 +63,7 @@
     "which": "^6.0.0",
     "zod": "^3.23.0",
     "@pugi/personas": "0.1.2",
-    "@pugi/sdk": "0.1.0-beta.89"
+    "@pugi/sdk": "0.1.0-beta.90"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",