@aitherium/shell-cli 1.11.1 → 1.12.0

package/dist/commands.js

@@ -761,6 +761,151 @@ const COMMANDS = {
             console.log();
         },
     },
+    spec: {
+        description: "Spec Ledger — list/inspect specs, ingest a PRD, publish issues, reasoner",
+        usage: '/spec [list | status <id> | ingest <path|url> [--pack x] | publish <id> [--repo o/n] [--new "Title"|--board o/n|--no-board] [--go] | reasoner [mode] | settings [--repo o/n] [--board o/n]]',
+        handler: async (client, args) => {
+            const parts = args.trim().split(/\s+/);
+            const sub = (parts[0] || 'list').toLowerCase();
+            const flag = (name) => {
+                const m = args.match(new RegExp(`--${name}\\s+("[^"]+"|\\S+)`));
+                return m ? m[1].replace(/^"|"$/g, '') : '';
+            };
+            if (sub === 'list' || sub === '') {
+                const spinner = ora('Loading specs...').start();
+                const r = await client.get('/spec/list?limit=100');
+                spinner.stop();
+                const specs = r?.specs || [];
+                if (!specs.length) {
+                    console.log(chalk.dim('  No specs ingested yet — /spec ingest <path|url>'));
+                    return;
+                }
+                console.log();
+                for (const s of specs) {
+                    console.log(`  ${chalk.cyan(s.id)}  ${chalk.bold(s.title)}`);
+                    console.log(chalk.dim(`     ${s.requirement_count} reqs · ${s.conformance_pct}% conformant${s.target_pack ? ` · pack ${s.target_pack}` : ''}`));
+                }
+                console.log();
+                return;
+            }
+            if (sub === 'status') {
+                const id = parts[1];
+                if (!id) {
+                    console.log(chalk.dim('  Usage: /spec status <spec_id>'));
+                    return;
+                }
+                const spinner = ora('Loading...').start();
+                const r = await client.get(`/spec/${encodeURIComponent(id)}/status`);
+                spinner.stop();
+                if (!r || r.error || r.detail) {
+                    console.log(chalk.red(`  ${r?.error || r?.detail || 'not found'}`));
+                    return;
+                }
+                const ov = r.coverage?.overall || {};
+                console.log();
+                console.log(`  ${chalk.bold(r.title)} ${chalk.dim(`(${r.target_pack || 'untriaged'})`)}`);
+                console.log(`  ${ov.pct ?? 0}% conformant — ${ov.satisfied ?? 0}/${ov.total ?? 0} satisfied, ${(r.gaps || []).length} gaps`);
+                for (const [cat, c] of Object.entries(r.coverage?.by_category || {})) {
+                    console.log(chalk.dim(`     ${cat}: ${c.satisfied}/${c.total} (${c.pct}%)`));
+                }
+                console.log();
+                return;
+            }
+            if (sub === 'ingest') {
+                const src = parts[1];
+                if (!src) {
+                    console.log(chalk.dim('  Usage: /spec ingest <path|url> [--pack x]'));
+                    return;
+                }
+                const body = { background: false };
+                body[src.startsWith('http') ? 'url' : 'path'] = src;
+                const pack = flag('pack');
+                if (pack)
+                    body.target_pack = pack;
+                const spinner = ora('Ingesting + extracting (reasoner)...').start();
+                const r = await client.post('/spec/ingest', body);
+                spinner.stop();
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'ingest failed'}`));
+                    return;
+                }
+                console.log(chalk.green(`  Ingested ${chalk.cyan(r.spec_doc_id)} — ${r.requirement_count ?? 0} requirements`));
+                if (r.by_category)
+                    console.log(chalk.dim(`     ${Object.entries(r.by_category).map(([k, v]) => `${k}:${v}`).join(', ')}`));
+                return;
+            }
+            if (sub === 'reasoner') {
+                const mode = parts[1];
+                const r = mode
+                    ? await client.post('/spec/reasoner', { mode })
+                    : await client.get('/spec/reasoner');
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'reasoner call failed'}`));
+                    return;
+                }
+                console.log(`  Reasoner: ${chalk.cyan(r.effective)}  ${chalk.dim(`(available: ${(r.available_modes || []).join(', ')})`)}`);
+                return;
+            }
+            if (sub === 'settings') {
+                const repo = flag('repo'), board = flag('board');
+                let r;
+                if (repo || board) {
+                    const body = {};
+                    if (repo)
+                        body.publish_repo = repo;
+                    if (board)
+                        body.publish_project = board;
+                    r = await client.post('/spec/settings', body);
+                }
+                else {
+                    r = await client.get('/spec/settings');
+                }
+                if (!r || r.error) {
+                    console.log(chalk.red(`  ${r?.error || 'settings failed'}`));
+                    return;
+                }
+                console.log(`  Reasoner: ${chalk.cyan(r.reasoner_mode)} · publish_repo: ${chalk.cyan(r.publish_repo || '(unset)')} · board: ${chalk.cyan(r.publish_project || '(unset)')}`);
+                return;
+            }
+            if (sub === 'publish') {
+                const id = parts[1];
+                if (!id) {
+                    console.log(chalk.dim('  Usage: /spec publish <id> [--repo o/n] [--new "Title"|--board o/n|--no-board] [--go]'));
+                    return;
+                }
+                const go = /--go\b/.test(args);
+                const body = { dry_run: !go };
+                const repo = flag('repo');
+                if (repo)
+                    body.repo = repo; // else server uses spec_settings default
+                const newTitle = flag('new');
+                const board = flag('board');
+                if (newTitle)
+                    body.create_project_title = newTitle;
+                else if (board)
+                    body.project = board;
+                // --no-board: leave both unset → issues only
+                const spinner = ora(go ? 'Publishing issues...' : 'Dry-run preview...').start();
+                const r = await client.post(`/spec/${encodeURIComponent(id)}/publish-issues`, body);
+                spinner.stop();
+                if (!r || (r.error && !r.created)) {
+                    console.log(chalk.red(`  ${r?.error || 'publish failed'}`));
+                    return;
+                }
+                const created = r.created?.length ?? 0, skipped = r.skipped_existing?.length ?? 0, errs = r.errors?.length ?? 0;
+                console.log();
+                console.log(`  ${go ? chalk.green(`Published ${created}`) : chalk.yellow(`Would create ${created}`)} issue(s) on ${chalk.cyan(r.repo)}` +
+                    (skipped ? `, skipped ${skipped}` : '') + (errs ? chalk.red(`, ${errs} errors`) : '') + (r.project ? ` → board ${chalk.cyan(r.project)}` : ''));
+                if (errs)
+                    console.log(chalk.red(`     ${r.errors[0]}`));
+                if (!go)
+                    console.log(chalk.dim('     (dry-run — add --go to actually publish)'));
+                console.log();
+                return;
+            }
+            console.log(chalk.dim('  Usage: /spec [list | status <id> | ingest <path|url> | publish <id> | reasoner [mode] | settings]'));
+        },
+    },
     atlas: {
         description: "Atlas PM board — latest cycle, in-flight items, or run a cycle",
         usage: '/atlas [board|tick] [--items N] [--sync]',

package/dist/doc-view.d.ts

@@ -0,0 +1,35 @@
+/**
+ * doc-view.ts — Load a file and render it into lines for the in-TUI document
+ * viewer (`/view <path>`): markdown gets the full terminal-markdown render,
+ * code/text get a line-numbered gutter, and images render inline as half-blocks
+ * (see image-preview.ts). The pure load/render logic lives here so it's testable
+ * and so both the viewer overlay and a future `/edit` share one classifier.
+ */
+export type DocKind = 'markdown' | 'code' | 'text' | 'image' | 'binary' | 'missing';
+export interface LoadedDoc {
+    kind: DocKind;
+    absPath: string;
+    title: string;
+    ext: string;
+    sizeBytes: number;
+    /** Raw text content (text/code/markdown only). */
+    text?: string;
+    /** Error/explanatory note for the header line. */
+    note?: string;
+}
+/** Resolve a user-supplied path against cwd + the known AitherOS roots. */
+export declare function resolveDocPath(input: string): string;
+/** Load + classify a file. Never throws. */
+export declare function loadDoc(input: string): LoadedDoc;
+export interface ViewRender {
+    lines: string[];
+    /** When the doc is an image the viewer couldn't render inline (non-PNG), the
+     *  caller should OS-open this path instead. */
+    fallbackOpenPath?: string;
+}
+/**
+ * Render a loaded doc into display lines for the viewer overlay, wrapped to
+ * `width` columns. Markdown → terminal markdown; code/text → line-numbered;
+ * image → inline half-blocks (PNG) or a note + OS-open fallback.
+ */
+export declare function renderDocLines(doc: LoadedDoc, width: number): ViewRender;

package/dist/doc-view.js

@@ -0,0 +1,144 @@
+/**
+ * doc-view.ts — Load a file and render it into lines for the in-TUI document
+ * viewer (`/view <path>`): markdown gets the full terminal-markdown render,
+ * code/text get a line-numbered gutter, and images render inline as half-blocks
+ * (see image-preview.ts). The pure load/render logic lives here so it's testable
+ * and so both the viewer overlay and a future `/edit` share one classifier.
+ */
+import { existsSync, readFileSync, statSync } from 'node:fs';
+import { basename, extname, isAbsolute, resolve } from 'node:path';
+import chalk from 'chalk';
+import { renderMarkdown, stripOsc8, resolveImagePath } from './renderer.js';
+import { imageToAnsi, imageDimensions } from './image-preview.js';
+const MARKDOWN_EXTS = new Set(['.md', '.markdown', '.mdx']);
+const IMAGE_EXTS = new Set(['.png', '.apng', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg', '.ico']);
+const CODE_EXTS = new Set([
+    '.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.rs', '.go', '.java',
+    '.c', '.h', '.cpp', '.hpp', '.cs', '.rb', '.php', '.sh', '.ps1', '.psm1',
+    '.sql', '.css', '.scss', '.html', '.xml', '.toml', '.ini', '.dockerfile',
+]);
+const DATA_EXTS = new Set(['.json', '.yaml', '.yml', '.csv', '.log', '.txt', '.env', '.conf', '.cfg']);
+/** Map a file extension to a markdown fence language for syntax highlighting. */
+function fenceLang(ext) {
+    const e = ext.replace(/^\./, '');
+    const map = {
+        ts: 'typescript', tsx: 'tsx', js: 'javascript', jsx: 'jsx', mjs: 'javascript',
+        py: 'python', rs: 'rust', go: 'go', rb: 'ruby', ps1: 'powershell', psm1: 'powershell',
+        yml: 'yaml', sh: 'bash',
+    };
+    return map[e] || e || '';
+}
+/** Resolve a user-supplied path against cwd + the known AitherOS roots. */
+export function resolveDocPath(input) {
+    const raw = input.replace(/^["']|["']$/g, '').trim();
+    if (isAbsolute(raw) && existsSync(raw))
+        return raw;
+    const cwdTry = resolve(process.cwd(), raw);
+    if (existsSync(cwdTry))
+        return cwdTry;
+    // Reuse the renderer's AitherOS-root resolver (handles Library/ paths etc.).
+    try {
+        const r = resolveImagePath(raw);
+        if (existsSync(r))
+            return r;
+    }
+    catch { /* */ }
+    return cwdTry; // best-effort; caller checks existsSync via kind === 'missing'
+}
+/** Load + classify a file. Never throws. */
+export function loadDoc(input) {
+    const absPath = resolveDocPath(input);
+    const ext = extname(absPath).toLowerCase();
+    const title = basename(absPath);
+    if (!existsSync(absPath)) {
+        return { kind: 'missing', absPath, title, ext, sizeBytes: 0, note: 'file not found' };
+    }
+    let sizeBytes = 0;
+    try {
+        const st = statSync(absPath);
+        sizeBytes = st.size;
+        if (st.isDirectory()) {
+            return { kind: 'missing', absPath, title, ext, sizeBytes: 0, note: 'is a directory (pass a file)' };
+        }
+    }
+    catch { /* */ }
+    if (IMAGE_EXTS.has(ext)) {
+        return { kind: 'image', absPath, title, ext, sizeBytes };
+    }
+    // Read as text (cap at 2 MB so a huge log doesn't stall the render).
+    const CAP = 2 * 1024 * 1024;
+    let text;
+    try {
+        const buf = readFileSync(absPath);
+        if (buf.includes(0)) {
+            return { kind: 'binary', absPath, title, ext, sizeBytes, note: 'binary file' };
+        }
+        text = buf.length > CAP
+            ? buf.subarray(0, CAP).toString('utf-8') + '\n…(truncated)…'
+            : buf.toString('utf-8');
+    }
+    catch (e) {
+        return { kind: 'binary', absPath, title, ext, sizeBytes, note: e?.message || 'unreadable' };
+    }
+    if (MARKDOWN_EXTS.has(ext))
+        return { kind: 'markdown', absPath, title, ext, sizeBytes, text };
+    if (CODE_EXTS.has(ext) || DATA_EXTS.has(ext))
+        return { kind: 'code', absPath, title, ext, sizeBytes, text };
+    return { kind: 'text', absPath, title, ext, sizeBytes, text };
+}
+function humanSize(n) {
+    if (n < 1024)
+        return `${n} B`;
+    if (n < 1024 * 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${(n / 1024 / 1024).toFixed(1)} MB`;
+}
+/**
+ * Render a loaded doc into display lines for the viewer overlay, wrapped to
+ * `width` columns. Markdown → terminal markdown; code/text → line-numbered;
+ * image → inline half-blocks (PNG) or a note + OS-open fallback.
+ */
+export function renderDocLines(doc, width) {
+    const innerW = Math.max(20, width - 2);
+    if (doc.kind === 'missing' || doc.kind === 'binary') {
+        return { lines: [chalk.red(`  ${doc.note || doc.kind}`), chalk.dim(`  ${doc.absPath}`)] };
+    }
+    if (doc.kind === 'image') {
+        const dims = imageDimensions(doc.absPath);
+        const header = [
+            chalk.dim(`  ${humanSize(doc.sizeBytes)}${dims ? ` · ${dims.width}×${dims.height}` : ''}`),
+            '',
+        ];
+        const ansi = imageToAnsi(doc.absPath, Math.min(innerW, 100), 44);
+        if (ansi)
+            return { lines: [...header, ...ansi.map(l => ' ' + l)] };
+        // Non-PNG (JPEG/WEBP/…): can't decode without a dep — OS-open instead.
+        return {
+            lines: [
+                ...header,
+                chalk.yellow(`  ${doc.ext.replace('.', '').toUpperCase()} preview not supported inline — opening in your OS viewer.`),
+                chalk.dim('  (PNG renders inline; other formats open externally.)'),
+            ],
+            fallbackOpenPath: doc.absPath,
+        };
+    }
+    if (doc.kind === 'markdown' && doc.text != null) {
+        const rendered = stripOsc8(renderMarkdown(doc.text));
+        return { lines: rendered.replace(/\n$/, '').split('\n') };
+    }
+    // code / text → line-numbered gutter.
+    const text = doc.text ?? '';
+    const rawLines = text.split('\n');
+    const gutterW = String(rawLines.length).length;
+    const lang = doc.kind === 'code' ? fenceLang(doc.ext) : '';
+    const out = [];
+    rawLines.forEach((ln, i) => {
+        const num = chalk.dim(String(i + 1).padStart(gutterW, ' ') + ' │ ');
+        // Light, dependency-free emphasis for code: comments dimmed.
+        let body = ln;
+        if (lang && /^\s*(#|\/\/|--|;)/.test(ln))
+            body = chalk.dim(ln);
+        out.push(num + body);
+    });
+    return { lines: out };
+}

package/dist/image-preview.d.ts

@@ -0,0 +1,45 @@
+/**
+ * image-preview.ts — Render raster images INLINE in the terminal as Unicode
+ * half-blocks (▀) with 24-bit colour.
+ *
+ * Why half-blocks instead of sixel / iTerm2 / kitty graphics: those protocols
+ * each work in only SOME terminals (sixel needs Windows Terminal ≥1.22, iTerm2's
+ * OSC-1337 needs iTerm2/WezTerm, kitty needs kitty) and several need the image
+ * re-encoded. The half-block trick — print '▀' with the FOREGROUND set to the top
+ * pixel and the BACKGROUND to the bottom pixel, so one character cell shows TWO
+ * vertical pixels — works in EVERY 24-bit-colour terminal, including the Windows
+ * Terminal the fleet runs on. Decoding uses node's built-in zlib (no new deps),
+ * so PNG (the format ComfyUI/AitherCanvas emit) renders for real; other formats
+ * fall back to the OS viewer at the call site.
+ */
+export interface DecodedImage {
+    width: number;
+    height: number;
+    /** RGBA, 4 bytes per pixel, row-major. */
+    rgba: Uint8Array;
+}
+/**
+ * Minimal PNG decoder — enough for the 8-bit images the fleet produces:
+ * colour types 0 (grey), 2 (RGB), 3 (palette), 6 (RGBA), and all 5 scanline
+ * filters. Returns null for anything it can't handle (interlaced, 16-bit, etc.)
+ * so the caller can fall back to the OS viewer.
+ */
+export declare function decodePNG(buf: Buffer): DecodedImage | null;
+/**
+ * Render a decoded image as half-block ANSI lines scaled to fit `cols` columns
+ * (each line is one terminal row = two image rows). Preserves aspect ratio;
+ * terminal cells are ~2× tall as wide, which the half-block already accounts for
+ * (2 pixels per cell vertically).
+ */
+export declare function renderHalfBlock(img: DecodedImage, cols: number, maxRows?: number): string[];
+/**
+ * Read an image file and render it inline as half-block ANSI lines, scaled to
+ * `cols`. Returns null when the format isn't decodable here (JPEG/GIF/WEBP/…),
+ * so the caller can fall back to the OS viewer. Never throws.
+ */
+export declare function imageToAnsi(absPath: string, cols: number, maxRows?: number): string[] | null;
+/** Cheap dimensions probe for the metadata header (PNG only; null otherwise). */
+export declare function imageDimensions(absPath: string): {
+    width: number;
+    height: number;
+} | null;

package/dist/image-preview.js

@@ -0,0 +1,250 @@
+/**
+ * image-preview.ts — Render raster images INLINE in the terminal as Unicode
+ * half-blocks (▀) with 24-bit colour.
+ *
+ * Why half-blocks instead of sixel / iTerm2 / kitty graphics: those protocols
+ * each work in only SOME terminals (sixel needs Windows Terminal ≥1.22, iTerm2's
+ * OSC-1337 needs iTerm2/WezTerm, kitty needs kitty) and several need the image
+ * re-encoded. The half-block trick — print '▀' with the FOREGROUND set to the top
+ * pixel and the BACKGROUND to the bottom pixel, so one character cell shows TWO
+ * vertical pixels — works in EVERY 24-bit-colour terminal, including the Windows
+ * Terminal the fleet runs on. Decoding uses node's built-in zlib (no new deps),
+ * so PNG (the format ComfyUI/AitherCanvas emit) renders for real; other formats
+ * fall back to the OS viewer at the call site.
+ */
+import { readFileSync } from 'node:fs';
+import { inflateSync } from 'node:zlib';
+/** Paeth predictor (PNG filter type 4). */
+function paeth(a, b, c) {
+    const p = a + b - c;
+    const pa = Math.abs(p - a);
+    const pb = Math.abs(p - b);
+    const pc = Math.abs(p - c);
+    if (pa <= pb && pa <= pc)
+        return a;
+    if (pb <= pc)
+        return b;
+    return c;
+}
+/**
+ * Minimal PNG decoder — enough for the 8-bit images the fleet produces:
+ * colour types 0 (grey), 2 (RGB), 3 (palette), 6 (RGBA), and all 5 scanline
+ * filters. Returns null for anything it can't handle (interlaced, 16-bit, etc.)
+ * so the caller can fall back to the OS viewer.
+ */
+export function decodePNG(buf) {
+    // Signature.
+    const SIG = [137, 80, 78, 71, 13, 10, 26, 10];
+    for (let i = 0; i < 8; i++)
+        if (buf[i] !== SIG[i])
+            return null;
+    let pos = 8;
+    let width = 0, height = 0, bitDepth = 0, colorType = 0, interlace = 0;
+    let palette = null;
+    let trns = null;
+    const idat = [];
+    while (pos < buf.length) {
+        const len = buf.readUInt32BE(pos);
+        pos += 4;
+        const type = buf.toString('ascii', pos, pos + 4);
+        pos += 4;
+        const data = buf.subarray(pos, pos + len);
+        pos += len;
+        pos += 4; // CRC — skip.
+        if (type === 'IHDR') {
+            width = data.readUInt32BE(0);
+            height = data.readUInt32BE(4);
+            bitDepth = data[8];
+            colorType = data[9];
+            interlace = data[12];
+        }
+        else if (type === 'PLTE') {
+            palette = new Uint8Array(data);
+        }
+        else if (type === 'tRNS') {
+            trns = new Uint8Array(data);
+        }
+        else if (type === 'IDAT') {
+            idat.push(Buffer.from(data));
+        }
+        else if (type === 'IEND') {
+            break;
+        }
+    }
+    if (!width || !height)
+        return null;
+    if (bitDepth !== 8)
+        return null; // 1/2/4/16-bit unsupported (keep it small)
+    if (interlace !== 0)
+        return null; // Adam7 unsupported
+    const channels = colorType === 2 ? 3 : colorType === 6 ? 4 : colorType === 0 ? 1 : colorType === 3 ? 1 : 0;
+    if (channels === 0)
+        return null;
+    let raw;
+    try {
+        raw = inflateSync(Buffer.concat(idat));
+    }
+    catch {
+        return null;
+    }
+    const stride = width * channels;
+    const out = new Uint8Array(width * height * 4);
+    const line = new Uint8Array(stride);
+    const prev = new Uint8Array(stride);
+    let rp = 0;
+    for (let y = 0; y < height; y++) {
+        const filter = raw[rp++];
+        for (let x = 0; x < stride; x++) {
+            const rawByte = raw[rp++];
+            const a = x >= channels ? line[x - channels] : 0;
+            const b = prev[x];
+            const c = x >= channels ? prev[x - channels] : 0;
+            let val;
+            switch (filter) {
+                case 0:
+                    val = rawByte;
+                    break;
+                case 1:
+                    val = rawByte + a;
+                    break;
+                case 2:
+                    val = rawByte + b;
+                    break;
+                case 3:
+                    val = rawByte + ((a + b) >> 1);
+                    break;
+                case 4:
+                    val = rawByte + paeth(a, b, c);
+                    break;
+                default:
+                    val = rawByte;
+                    break;
+            }
+            line[x] = val & 0xff;
+        }
+        // Expand the scanline into RGBA.
+        for (let x = 0; x < width; x++) {
+            const o = (y * width + x) * 4;
+            if (colorType === 2) { // RGB
+                out[o] = line[x * 3];
+                out[o + 1] = line[x * 3 + 1];
+                out[o + 2] = line[x * 3 + 2];
+                out[o + 3] = 255;
+            }
+            else if (colorType === 6) { // RGBA
+                out[o] = line[x * 4];
+                out[o + 1] = line[x * 4 + 1];
+                out[o + 2] = line[x * 4 + 2];
+                out[o + 3] = line[x * 4 + 3];
+            }
+            else if (colorType === 0) { // grey
+                const g = line[x];
+                out[o] = g;
+                out[o + 1] = g;
+                out[o + 2] = g;
+                out[o + 3] = 255;
+            }
+            else if (colorType === 3 && palette) { // palette
+                const idx = line[x];
+                out[o] = palette[idx * 3];
+                out[o + 1] = palette[idx * 3 + 1];
+                out[o + 2] = palette[idx * 3 + 2];
+                out[o + 3] = trns && idx < trns.length ? trns[idx] : 255;
+            }
+        }
+        prev.set(line);
+    }
+    return { width, height, rgba: out };
+}
+/** Nearest-neighbour sample of the source image at normalised (u,v) → RGBA. */
+function sample(img, u, v) {
+    const x = Math.min(img.width - 1, Math.max(0, Math.floor(u * img.width)));
+    const y = Math.min(img.height - 1, Math.max(0, Math.floor(v * img.height)));
+    const o = (y * img.width + x) * 4;
+    return [img.rgba[o], img.rgba[o + 1], img.rgba[o + 2], img.rgba[o + 3]];
+}
+/** Composite a pixel over a dark checkerboard so transparency reads correctly. */
+function overBg(r, g, b, a, dark) {
+    if (a >= 255)
+        return [r, g, b];
+    const bg = dark ? 30 : 45;
+    const af = a / 255;
+    return [
+        Math.round(r * af + bg * (1 - af)),
+        Math.round(g * af + bg * (1 - af)),
+        Math.round(b * af + bg * (1 - af)),
+    ];
+}
+/**
+ * Render a decoded image as half-block ANSI lines scaled to fit `cols` columns
+ * (each line is one terminal row = two image rows). Preserves aspect ratio;
+ * terminal cells are ~2× tall as wide, which the half-block already accounts for
+ * (2 pixels per cell vertically).
+ */
+export function renderHalfBlock(img, cols, maxRows = 40) {
+    const aspect = img.height / img.width;
+    let outCols = Math.max(1, Math.min(cols, img.width));
+    // rows of CELLS; each cell = 2 vertical pixels, and a cell is ~2× tall as wide.
+    let outRows = Math.max(1, Math.round((outCols * aspect) / 2));
+    if (outRows > maxRows) {
+        outRows = maxRows;
+        outCols = Math.max(1, Math.round((outRows * 2) / aspect));
+    }
+    outCols = Math.min(outCols, cols);
+    const lines = [];
+    for (let ry = 0; ry < outRows; ry++) {
+        let line = '';
+        for (let cx = 0; cx < outCols; cx++) {
+            const u = (cx + 0.5) / outCols;
+            const vTop = (ry * 2 + 0.5) / (outRows * 2);
+            const vBot = (ry * 2 + 1.5) / (outRows * 2);
+            const [tr, tg, tb, ta] = sample(img, u, vTop);
+            const [br, bg, bb, ba] = sample(img, u, vBot);
+            const [TR, TG, TB] = overBg(tr, tg, tb, ta, true);
+            const [BR, BG, BB] = overBg(br, bg, bb, ba, true);
+            // '▀' upper half-block: fg = top pixel, bg = bottom pixel.
+            line += `\x1b[38;2;${TR};${TG};${TB}m\x1b[48;2;${BR};${BG};${BB}m▀`;
+        }
+        line += '\x1b[0m';
+        lines.push(line);
+    }
+    return lines;
+}
+const PNG_EXTS = new Set(['.png', '.apng']);
+/**
+ * Read an image file and render it inline as half-block ANSI lines, scaled to
+ * `cols`. Returns null when the format isn't decodable here (JPEG/GIF/WEBP/…),
+ * so the caller can fall back to the OS viewer. Never throws.
+ */
+export function imageToAnsi(absPath, cols, maxRows = 40) {
+    try {
+        const dot = absPath.lastIndexOf('.');
+        const ext = dot >= 0 ? absPath.slice(dot).toLowerCase() : '';
+        if (!PNG_EXTS.has(ext))
+            return null; // only PNG decodes without a dep
+        const buf = readFileSync(absPath);
+        const img = decodePNG(buf);
+        if (!img)
+            return null;
+        return renderHalfBlock(img, cols, maxRows);
+    }
+    catch {
+        return null;
+    }
+}
+/** Cheap dimensions probe for the metadata header (PNG only; null otherwise). */
+export function imageDimensions(absPath) {
+    try {
+        const buf = readFileSync(absPath, { flag: 'r' });
+        if (buf.length < 24)
+            return null;
+        // PNG: IHDR width/height at bytes 16..24.
+        const isPng = buf[0] === 0x89 && buf[1] === 0x50 && buf[2] === 0x4e && buf[3] === 0x47;
+        if (isPng)
+            return { width: buf.readUInt32BE(16), height: buf.readUInt32BE(20) };
+        return null;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/main.js

@@ -1,7 +1,19 @@
 #!/usr/bin/env node
-// Trust AitherOS self-signed TLS certs without disabling all verification.
-// Prefer NODE_EXTRA_CA_CERTS (adds our CA to the trust chain) if available;
-// only fall back to NODE_TLS_REJECT_UNAUTHORIZED=0 when no CA chain exists.
+// Trust AitherOS internal TLS certs.
+//
+// Reality of the fleet's PKI: each internal service ships a SELF-SIGNED leaf
+// (e.g. Identity at :8115 → subject==issuer CN=aitheros-identity, no SAN for
+// 127.0.0.1). Those certs are NOT issued by ca-chain.pem and carry no loopback
+// SAN, so NODE_EXTRA_CA_CERTS can never validate them — under Node, fetch() to an
+// https-only internal service (Identity) fails cert/hostname verification and the
+// status banner false-flags it DOWN even though it's up. (Bun ignores
+// NODE_EXTRA_CA_CERTS entirely; its per-request `tls` opt is handled in the probe.)
+//
+// So: when the primary endpoint is a LOCAL/loopback fleet (the self-signed trust
+// domain), disable verification. For a PUBLIC endpoint (idp/gateway.aitherium.com,
+// real CA-issued certs) keep strict TLS — those validate normally and must stay
+// protected against MITM. NODE_EXTRA_CA_CERTS is still set when present (harmless,
+// and helps any service that IS chain-issued).
 import { existsSync } from 'fs';
 import { join, basename } from 'path';
 const _caChainPaths = [
@@ -10,11 +22,26 @@ const _caChainPaths = [
     '/app/AitherOS/Library/Data/tls/ca-chain.pem',
 ];
 const _caChain = _caChainPaths.find(p => p && existsSync(p));
-if (_caChain) {
+if (_caChain)
     process.env.NODE_EXTRA_CA_CERTS = _caChain;
-}
-else {
-    // No CA chain found — disable verification as last resort (suppress warning via env)
+// Resolve the primary endpoint the same way loadConfig() does (env precedence),
+// then decide if we're in the internal self-signed trust domain.
+const _primaryUrl = process.env.AITHER_API_URL || process.env.AITHER_GENESIS_URL ||
+    process.env.AITHER_GATEWAY_URL || 'http://127.0.0.1:8001';
+const _isLoopbackFleet = (() => {
+    try {
+        const h = new URL(_primaryUrl).hostname;
+        return h === 'localhost' || h === '127.0.0.1' || h === '::1' ||
+            /^10\./.test(h) || /^192\.168\./.test(h) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+            h.endsWith('.local') || h.endsWith('.internal');
+    }
+    catch {
+        return true;
+    } // unparseable → assume local dev
+})();
+// Explicit override always wins; otherwise relax only for the loopback fleet.
+if (process.env.NODE_TLS_REJECT_UNAUTHORIZED == null && _isLoopbackFleet) {
     process.env.NODE_TLS_REJECT_UNAUTHORIZED = '0';
 }
 /**
@@ -79,7 +106,7 @@ async function resolveResume(client, config, mode, id) {
 // Install global crash reporter — catches uncaught exceptions/rejections,
 // prompts user to send error report, creates GitHub issue automatically.
 installCrashReporter();
-const VERSION = '1.10.0'; // keep in sync with package.json
+const VERSION = '1.12.0'; // keep in sync with package.json
 async function main() {
     const args = process.argv.slice(2);
     if (args.includes('--help') || args.includes('-h')) {

package/dist/renderer.js

@@ -33,7 +33,7 @@ export function osc8Link(url, label) {
 }
 /* ── Banner ─────────────────────────────────────────────────── */
 export function renderBanner(info) {
-    const version = 'v1.11.1'; // keep in sync with package.json
+    const version = 'v1.12.0'; // keep in sync with package.json
     const title = `AitherShell ${version}`;
     let connected;
     if (info.genesisOnline === true) {

package/dist/status-banner.js

@@ -13,14 +13,34 @@
  * connect banner and the TUI share one implementation.
  */
 import chalk from 'chalk';
+/** Loopback/private hosts serve the internal self-signed CA. Bun's `fetch`
+ *  ignores NODE_EXTRA_CA_CERTS (set in main.ts), so an https probe to an internal
+ *  service — notably Identity at :8115, which is https-ONLY (http → 400) — fails
+ *  cert validation and gets false-flagged DOWN even though it's up. Health probes
+ *  carry no secrets, so accept the internal cert for private hosts; PUBLIC remote
+ *  endpoints (idp/gateway, real valid certs) keep strict TLS validation. */
+function insecureTlsFor(url) {
+    try {
+        const h = new URL(url).hostname;
+        const isPrivate = h === 'localhost' || h === '127.0.0.1' || h === '::1' ||
+            /^10\./.test(h) || /^192\.168\./.test(h) ||
+            /^172\.(1[6-9]|2\d|3[01])\./.test(h) ||
+            h.endsWith('.local') || h.endsWith('.internal');
+        // `tls` is Bun's per-request option (the shipped binary is Bun-compiled);
+        // Node's fetch ignores it harmlessly.
+        return isPrivate ? { tls: { rejectUnauthorized: false } } : {};
+    }
+    catch {
+        return {};
+    }
+}
 /** Probe a health endpoint, tolerating http↔https and a single cold-start miss. */
 export async function probeHealth(url, timeoutMs = 4000) {
     const tryFetch = async (u) => {
         try {
             const r = await fetch(u, {
                 signal: AbortSignal.timeout(timeoutMs),
-                // @ts-ignore — Node 18+ supports this for self-signed certs
-                ...(u.startsWith('https') ? { dispatcher: undefined } : {}),
+                ...insecureTlsFor(u),
             });
             return r.ok;
         }

package/dist/tui/repl-tui.js

@@ -10,7 +10,7 @@
  * for those; everything else runs in-pane.
  */
 import { execSync } from 'node:child_process';
-import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
 import chalk from 'chalk';
 import { setActiveConfig } from '../config.js';
@@ -21,6 +21,9 @@ import { collectArgs } from '../interactive.js';
 import { gatherStatus, formatStatusLines } from '../status-banner.js';
 import { setJobNotifier, listJobs, getJob, cancelJob, runningCount, launchChatJob, launchForgeJob, launchSwarmJob, launchCommandJob, formatJobLine, formatJobOutput, } from '../jobs.js';
 import { configureRemoteSync, recordTurn, loadSession, buildContextSummary } from '../session-store.js';
+import { openLocalImage } from '../renderer.js';
+import { loadDoc, renderDocLines, resolveDocPath } from '../doc-view.js';
+import { imageToAnsi, imageDimensions } from '../image-preview.js';
 import { createTuiScreen } from './screen.js';
 import { createTuiRenderer } from './controller.js';
 import { setTuiActive } from '../crash-reporter.js';
@@ -625,6 +628,89 @@ export async function startTuiRepl(client, config) {
         surface.outputLine(chalk.dim('  📡 Left relay — back to agent chat.'));
         idleStatus();
     }
+    /** `/view <path>` — open a file in the in-TUI document viewer. Markdown/code/
+     *  text render in a full-screen scrollable overlay; PNG images render inline as
+     *  half-blocks on the real terminal (via runDetached, for true 24-bit colour);
+     *  other image formats open in the OS viewer. */
+    async function handleView(args) {
+        const path = args.trim();
+        if (!path) {
+            surface.outputLine(chalk.yellow('Usage: /view <file>') + chalk.dim('  — markdown, code, text, or a PNG image'));
+            surface.focusInput();
+            return;
+        }
+        const doc = loadDoc(path);
+        if (doc.kind === 'missing' || doc.kind === 'binary') {
+            surface.outputLine(chalk.yellow(`  ${doc.note || doc.kind}: `) + chalk.dim(doc.absPath));
+            surface.focusInput();
+            return;
+        }
+        if (doc.kind === 'image') {
+            const cols = Math.max(20, (process.stdout.columns || 100) - 4);
+            const ansi = imageToAnsi(doc.absPath, Math.min(cols, 120), 50);
+            if (ansi) {
+                const dims = imageDimensions(doc.absPath);
+                await surface.runDetached(`view ${doc.title}`, () => {
+                    process.stdout.write(chalk.dim(`  ${doc.title}${dims ? `  ${dims.width}×${dims.height}` : ''}\n\n`));
+                    for (const l of ansi)
+                        process.stdout.write('  ' + l + '\n');
+                });
+                idleStatus();
+            }
+            else {
+                openLocalImage(doc.absPath);
+                surface.outputLine(chalk.dim(`  🖼  ${doc.ext.replace('.', '').toUpperCase()} opened in OS viewer (only PNG renders inline): `) + chalk.dim(doc.absPath));
+                surface.focusInput();
+            }
+            return;
+        }
+        const width = (process.stdout.columns || 100);
+        const { lines, fallbackOpenPath } = renderDocLines(doc, width);
+        if (fallbackOpenPath)
+            openLocalImage(fallbackOpenPath);
+        await surface.showViewer(doc.title, lines);
+        idleStatus();
+    }
+    /** `/edit <path>` — open a file in the in-TUI editor (notepad/vim-lite). Opens
+     *  an empty buffer for a non-existent path (create-on-save). Refuses image/
+     *  binary files. Ctrl+S writes the file; Esc/Ctrl+Q closes. */
+    async function handleEdit(args) {
+        const path = args.trim();
+        if (!path) {
+            surface.outputLine(chalk.yellow('Usage: /edit <file>') + chalk.dim('  — opens the in-shell editor (^S save · ^Q quit)'));
+            surface.focusInput();
+            return;
+        }
+        const absPath = resolveDocPath(path);
+        let initial = '';
+        if (existsSync(absPath)) {
+            const doc = loadDoc(path);
+            if (doc.kind === 'image' || doc.kind === 'binary') {
+                surface.outputLine(chalk.yellow(`  cannot edit a ${doc.kind} file: `) + chalk.dim(absPath));
+                surface.focusInput();
+                return;
+            }
+            initial = doc.text ?? '';
+        }
+        else {
+            surface.outputLine(chalk.dim(`  new file: ${absPath}`));
+        }
+        const title = absPath.split(/[/\\]/).pop() || path;
+        await surface.showEditor(title, initial, async (text) => {
+            try {
+                const dir = dirname(absPath);
+                if (!existsSync(dir))
+                    mkdirSync(dir, { recursive: true });
+                writeFileSync(absPath, text, 'utf-8');
+                return null;
+            }
+            catch (e) {
+                return e?.message || 'write failed';
+            }
+        });
+        surface.outputLine(chalk.dim(`  edited ${absPath}`));
+        idleStatus();
+    }
     async function runCommand(input, bg = false) {
         const sp = input.indexOf(' ');
         const name = sp > 0 ? input.slice(1, sp) : input.slice(1);
@@ -643,6 +729,14 @@ export async function startTuiRepl(client, config) {
             showHelp();
             return;
         }
+        if (name === 'view' || name === 'open' || name === 'cat') {
+            await handleView(args);
+            return;
+        }
+        if (name === 'edit' || name === 'e' || name === 'nano') {
+            await handleEdit(args);
+            return;
+        }
         if (name === 'jobs') {
             handleJobs(args);
             return;

package/dist/tui/screen.d.ts

@@ -43,6 +43,13 @@ export interface TuiSurface {
     pickerOpen(): boolean;
     /** Show a filterable command picker; resolves with the chosen value or null. */
     showPicker(title: string, items: PickerItem[], initialFilter?: string): Promise<string | null>;
+    /** Show a full-screen scrollable document viewer over pre-rendered lines
+     *  (markdown/code/text). Resolves when the user closes it (q/Esc). */
+    showViewer(title: string, lines: string[]): Promise<void>;
+    /** Show a full-screen multi-line text editor seeded with `initialText`.
+     *  `onSave(text)` persists and returns an error string (or null on success).
+     *  Resolves when the user closes the editor (Esc/Ctrl+Q). */
+    showEditor(title: string, initialText: string, onSave: (text: string) => Promise<string | null>): Promise<void>;
     /**
      * Suspend the blessed screen, run `fn` on the REAL terminal (so command
      * handlers' console.log / ora spinners / @inquirer prompts all work and don't

package/dist/tui/screen.js

@@ -726,11 +726,320 @@ export function createTuiScreen(opts) {
             screen.render();
         });
     }
+    // ── Document viewer overlay (full-screen scrollable box) ──────
+    // Reuses the _pickerOpen guard so the main keypress handler stands down while
+    // the viewer owns the keyboard. Content is pre-rendered (markdown/code/text +
+    // chalk ANSI); blessed parses the SGR colour codes itself. Images do NOT come
+    // through here — they render via runDetached so 24-bit colour isn't downsampled.
+    function showViewer(title, lines) {
+        return new Promise((resolve) => {
+            _pickerOpen = true;
+            const box = blessed.box({
+                parent: screen, label: ` ${title}  —  ↑↓/PgUp/PgDn scroll · g/G top/bottom · q/Esc close `,
+                border: 'line', top: 0, left: 0, width: '100%', height: '100%',
+                tags: false, scrollable: true, alwaysScroll: true, keys: true, mouse: true,
+                scrollbar: { ch: ' ', inverse: true }, wrap: true,
+                style: { border: { fg: 'cyan' }, label: { fg: 'cyan' } },
+            });
+            box.setContent(lines.join('\n'));
+            function close() {
+                _pickerOpen = false;
+                try {
+                    box.destroy();
+                }
+                catch { /* */ }
+                screen.render();
+                focusInput();
+                resolve();
+            }
+            const vpage = () => Math.max(1, box.height - 3);
+            box.key(['q', 'escape', 'C-c'], () => close());
+            box.key(['up', 'k'], () => { box.scroll(-1); screen.render(); });
+            box.key(['down', 'j'], () => { box.scroll(1); screen.render(); });
+            box.key(['pageup'], () => { box.scroll(-vpage()); screen.render(); });
+            box.key(['pagedown', 'space'], () => { box.scroll(vpage()); screen.render(); });
+            box.key(['g', 'home'], () => { box.scrollTo(0); screen.render(); });
+            box.key(['G', 'end'], () => { box.setScrollPerc(100); screen.render(); });
+            box.on('wheelup', () => { box.scroll(-3); screen.render(); });
+            box.on('wheeldown', () => { box.scroll(3); screen.render(); });
+            box.focus();
+            screen.render();
+        });
+    }
+    // ── Document editor overlay (notepad/vim-lite, manual keypresses) ─────
+    // A real multi-line editor. We drive it from the PROGRAM keypress stream (same
+    // reason as the main input box: blessed's textarea double-delivers keys on this
+    // terminal). Lines are stored as code-point arrays so emoji/CJK caret maths is
+    // correct. While open, _pickerOpen suppresses the main onKey handler and a
+    // dedicated keypress listener owns the keyboard until the user quits.
+    function showEditor(title, initialText, onSave) {
+        return new Promise((resolve) => {
+            _pickerOpen = true;
+            const lines = (initialText.length ? initialText.replace(/\r\n/g, '\n').split('\n') : [''])
+                .map((l) => Array.from(l));
+            let cr = 0; // cursor row
+            let cc = 0; // cursor col (code-point index)
+            let top = 0; // first visible row (vertical scroll)
+            let dirty = false;
+            let msg = ''; // transient status message
+            let confirmingQuit = false;
+            const box = blessed.box({
+                parent: screen, border: 'line', top: 0, left: 0, width: '100%', height: '100%',
+                tags: false, style: { border: { fg: 'yellow' }, label: { fg: 'yellow' } },
+            });
+            const innerH = () => Math.max(1, box.height - 2);
+            const innerW = () => Math.max(20, box.width - 2);
+            const gutterW = () => String(lines.length).length;
+            function setLabel() {
+                const flag = dirty ? chalk.red(' ●') : '';
+                const pos = `${cr + 1}:${cc + 1}`;
+                const hint = confirmingQuit
+                    ? chalk.red('unsaved — ^Q again to discard, ^S to save')
+                    : chalk.dim('^S save · ^Q/Esc quit · arrows move · Enter newline');
+                const note = msg ? '  ' + chalk.green(msg) : '';
+                try {
+                    box.setLabel(` ${title}${flag}  ${chalk.dim(pos)}  ${hint}${note} `);
+                }
+                catch { /* */ }
+            }
+            function clampView() {
+                if (cr < top)
+                    top = cr;
+                if (cr >= top + innerH())
+                    top = cr - innerH() + 1;
+                if (top < 0)
+                    top = 0;
+            }
+            function render() {
+                clampView();
+                const g = gutterW();
+                const avail = innerW() - (g + 3); // gutter "NNN │ "
+                const out = [];
+                for (let r = top; r < Math.min(lines.length, top + innerH()); r++) {
+                    const isCur = r === cr;
+                    const cps = lines[r];
+                    // Horizontal window so the caret stays visible on long lines.
+                    let start = 0;
+                    if (isCur && cc > avail - 1)
+                        start = cc - (avail - 1);
+                    const slice = cps.slice(start, start + avail);
+                    const gutter = chalk.dim(String(r + 1).padStart(g, ' ') + ' │ ');
+                    if (isCur) {
+                        const rel = cc - start;
+                        const before = slice.slice(0, rel).join('');
+                        const atCh = slice[rel] ?? ' ';
+                        const after = slice.slice(rel + 1).join('');
+                        const lead = start > 0 ? chalk.dim('‹') : '';
+                        out.push(gutter + lead + before + chalk.inverse(atCh) + after);
+                    }
+                    else {
+                        out.push(gutter + slice.join(''));
+                    }
+                }
+                try {
+                    box.setContent(out.join('\n'));
+                }
+                catch { /* */ }
+                setLabel();
+                scheduleRender();
+            }
+            function curLine() { return lines[cr]; }
+            async function doSave() {
+                const text = lines.map((l) => l.join('')).join('\n');
+                const err = await onSave(text);
+                if (err) {
+                    msg = '';
+                    setLabel();
+                    try {
+                        box.setLabel(` ${title}  ${chalk.red('save failed: ' + err)} `);
+                    }
+                    catch { /* */ }
+                    scheduleRender();
+                }
+                else {
+                    dirty = false;
+                    confirmingQuit = false;
+                    msg = 'saved';
+                    render();
+                    setTimeout(() => { msg = ''; setLabel(); scheduleRender(); }, 1500);
+                }
+            }
+            function close() {
+                screen.program.removeListener('keypress', editorKey);
+                _pickerOpen = false;
+                try {
+                    box.destroy();
+                }
+                catch { /* */ }
+                screen.render();
+                focusInput();
+                resolve();
+            }
+            function editorKey(ch, key) {
+                const name = (key && key.name) || '';
+                const ctrl = !!(key && key.ctrl);
+                // Save / quit.
+                if (ctrl && name === 's') {
+                    void doSave();
+                    return;
+                }
+                if ((ctrl && name === 'q') || name === 'escape') {
+                    if (dirty && !confirmingQuit) {
+                        confirmingQuit = true;
+                        setLabel();
+                        scheduleRender();
+                        return;
+                    }
+                    close();
+                    return;
+                }
+                confirmingQuit = false;
+                // Navigation.
+                if (name === 'up') {
+                    if (cr > 0) {
+                        cr--;
+                        cc = Math.min(cc, curLine().length);
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'down') {
+                    if (cr < lines.length - 1) {
+                        cr++;
+                        cc = Math.min(cc, curLine().length);
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'left') {
+                    if (cc > 0)
+                        cc--;
+                    else if (cr > 0) {
+                        cr--;
+                        cc = curLine().length;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'right') {
+                    if (cc < curLine().length)
+                        cc++;
+                    else if (cr < lines.length - 1) {
+                        cr++;
+                        cc = 0;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'home') {
+                    cc = 0;
+                    render();
+                    return;
+                }
+                if (name === 'end') {
+                    cc = curLine().length;
+                    render();
+                    return;
+                }
+                if (name === 'pageup') {
+                    cr = Math.max(0, cr - innerH());
+                    cc = Math.min(cc, curLine().length);
+                    render();
+                    return;
+                }
+                if (name === 'pagedown') {
+                    cr = Math.min(lines.length - 1, cr + innerH());
+                    cc = Math.min(cc, curLine().length);
+                    render();
+                    return;
+                }
+                // Editing.
+                if (name === 'enter' || name === 'return' || name === 'linefeed') {
+                    const cur = curLine();
+                    const tail = cur.slice(cc);
+                    lines[cr] = cur.slice(0, cc);
+                    lines.splice(cr + 1, 0, tail);
+                    cr++;
+                    cc = 0;
+                    dirty = true;
+                    render();
+                    return;
+                }
+                if (name === 'backspace') {
+                    if (cc > 0) {
+                        curLine().splice(cc - 1, 1);
+                        cc--;
+                        dirty = true;
+                    }
+                    else if (cr > 0) {
+                        const cur = lines.splice(cr, 1)[0];
+                        cc = lines[cr - 1].length;
+                        lines[cr - 1] = lines[cr - 1].concat(cur);
+                        cr--;
+                        dirty = true;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'delete') {
+                    if (cc < curLine().length) {
+                        curLine().splice(cc, 1);
+                        dirty = true;
+                    }
+                    else if (cr < lines.length - 1) {
+                        const next = lines.splice(cr + 1, 1)[0];
+                        lines[cr] = curLine().concat(next);
+                        dirty = true;
+                    }
+                    render();
+                    return;
+                }
+                if (name === 'tab') {
+                    curLine().splice(cc, 0, ' ', ' ');
+                    cc += 2;
+                    dirty = true;
+                    render();
+                    return;
+                }
+                // Printable insert (paste may deliver several chars; respects newlines).
+                if (ch && typeof ch === 'string' && ch.length >= 1 && ch >= ' ' && !(key && (key.ctrl || key.meta))) {
+                    for (const c of Array.from(ch)) {
+                        curLine().splice(cc, 0, c);
+                        cc++;
+                    }
+                    dirty = true;
+                    render();
+                    return;
+                }
+                // Multi-line paste arriving as a chunk with embedded newlines.
+                if (ch && typeof ch === 'string' && ch.includes('\n')) {
+                    for (const c of Array.from(ch)) {
+                        if (c === '\n') {
+                            const tail = curLine().slice(cc);
+                            lines[cr] = curLine().slice(0, cc);
+                            lines.splice(cr + 1, 0, tail);
+                            cr++;
+                            cc = 0;
+                        }
+                        else if (c >= ' ') {
+                            curLine().splice(cc, 0, c);
+                            cc++;
+                        }
+                    }
+                    dirty = true;
+                    render();
+                    return;
+                }
+            }
+            screen.program.on('keypress', editorKey);
+            render();
+        });
+    }
     renderInput();
     screen.render();
     return {
         screen, input, appendOutput, outputLine, markCheckpoint, replaceOutputFrom, prependOutput,
         traceLine, startTraceTurn, finishTraceTurn, setStatus, setTracePanel, setOutputLabel, clearPanes, toggleTrace, render, focusInput, destroy,
-        pickerOpen, showPicker, runDetached,
+        pickerOpen, showPicker, showViewer, showEditor, runDetached,
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aitherium/shell-cli",
-  "version": "1.11.1",
+  "version": "1.12.0",
   "description": "Interactive terminal for AitherOS and ADK agents",
   "license": "BUSL-1.1",
   "type": "module",