synabun 2.0.9 → 2.1.0

package/neural-interface/public/shared/skills/studio/sx-editor-model.js

@@ -0,0 +1,193 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: what the editor shows about a document
+// ═══════════════════════════════════════════
+//
+// The facts of the status bar (lines, line endings, byte-order mark, bytes, an estimate of tokens with how it is
+// estimated), the description helper (how much of each runtime's budget a description uses, and whether it says
+// what the skill does and when to use it), the keys the form does not edit ("kept as written", the Advanced
+// section), and what kind of file a path is (Markdown, YAML, an image the viewer can show, other binary).
+// Measurements are named for what they are: characters, bytes, lines and an estimate of tokens (characters ÷ 4,
+// said as an estimate) are kept apart (master plan §3.2). No DOM; imports only what the page and the server share.
+
+import { PROFILES } from '../ss-profiles.js';
+import { FORM_FIELDS } from '../ss-form.js';
+
+/** Characters per token of the estimate (the usual rule of thumb for English text; said as "≈" with its method). */
+export const CHARS_PER_TOKEN = 4;
+/** The guidance for a SKILL.md body (Agent Skills and Claude Code best practice), not an upload limit. */
+export const BODY_GUIDANCE = Object.freeze({ lines: PROFILES['portable-six-field'].limits.bodyLinesGuidance, tokens: PROFILES['portable-six-field'].limits.bodyTokensGuidance });
+
+/** An estimate of tokens: characters ÷ 4, rounded up. */
+export const estimateTokens = (text) => Math.ceil(String(text ?? '').length / CHARS_PER_TOKEN);
+
+/** UTF-8 length of a text, without a TextEncoder (the page and Node count the same). */
+export function utf8Length(text) {
+  const s = String(text ?? '');
+  let n = 0;
+  for (let i = 0; i < s.length; i++) {
+    const c = s.charCodeAt(i);
+    if (c < 0x80) n += 1;
+    else if (c < 0x800) n += 2;
+    else if (c >= 0xD800 && c <= 0xDBFF && i + 1 < s.length && (s.charCodeAt(i + 1) & 0xFC00) === 0xDC00) { n += 4; i++; }
+    else n += 3;
+  }
+  return n;
+}
+
+const EXT = (path) => { const base = String(path ?? '').split('/').pop() || ''; const at = base.lastIndexOf('.'); return at > 0 ? base.slice(at + 1).toLowerCase() : ''; };
+const IMAGE_EXT = { png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', gif: 'image/gif', webp: 'image/webp', svg: 'image/svg+xml' };
+
+/** What a file is, for the tree and the viewer. */
+export function fileKind(path, { binary = false } = {}) {
+  const ext = EXT(path);
+  if (IMAGE_EXT[ext]) return { kind: 'image', mime: IMAGE_EXT[ext], ext };
+  if (binary) return { kind: 'binary', mime: 'application/octet-stream', ext };
+  if (ext === 'md' || ext === 'markdown') return { kind: 'markdown', mime: 'text/markdown', ext };
+  if (ext === 'yaml' || ext === 'yml') return { kind: 'yaml', mime: 'text/yaml', ext };
+  if (ext === 'json') return { kind: 'json', mime: 'application/json', ext };
+  if (['sh', 'bash', 'zsh', 'py', 'js', 'mjs', 'ts', 'rb', 'ps1'].includes(ext)) return { kind: 'script', mime: 'text/plain', ext };
+  return { kind: 'text', mime: 'text/plain', ext };
+}
+
+/** The line endings of a document, as the status bar says them. */
+export function eolLabel({ eol = '\n', mixed = false } = {}) {
+  if (mixed) return 'mixed';
+  return eol === '\r\n' ? 'CRLF' : eol === '\r' ? 'CR' : 'LF';
+}
+
+/**
+ * The facts of the status bar for one document.
+ * @param {{ path: string|null, text: string, eol?: string, mixed?: boolean, bom?: boolean, binary?: boolean,
+ *   size?: number, head?: boolean }} doc `head`: the skill's SKILL.md (its body is measured against the guidance)
+ */
+export function documentFacts(doc) {
+  const text = String(doc?.text ?? '');
+  const lines = text === '' ? 1 : text.split('\n').length;
+  const facts = {
+    binary: !!doc?.binary,
+    lines: doc?.binary ? null : lines,
+    chars: doc?.binary ? null : text.length,
+    bytes: doc?.binary ? (Number(doc?.size) || 0) : utf8Length(text) + (doc?.bom ? 3 : 0),
+    tokens: doc?.binary ? null : estimateTokens(text),
+    eol: doc?.binary ? null : eolLabel(doc || {}),
+    bom: !!doc?.bom,
+    kind: fileKind(doc?.path || 'SKILL.md', { binary: !!doc?.binary }).kind,
+    guidance: null,
+  };
+  if (doc?.head && !doc?.binary) {
+    const body = bodyOf(text);
+    const bodyLines = body.text === '' ? 0 : body.text.split('\n').length;
+    const bodyTokens = estimateTokens(body.text);
+    facts.guidance = {
+      lines: bodyLines, tokens: bodyTokens, maxLines: BODY_GUIDANCE.lines, maxTokens: BODY_GUIDANCE.tokens,
+      ratio: Math.min(1, Math.max(bodyLines / BODY_GUIDANCE.lines, bodyTokens / BODY_GUIDANCE.tokens)),
+      over: bodyLines > BODY_GUIDANCE.lines || bodyTokens > BODY_GUIDANCE.tokens,
+    };
+  }
+  return facts;
+}
+
+/** The body of a document (after its frontmatter), with the line it starts on. */
+export function bodyOf(text) {
+  const s = String(text ?? '').replace(/^/, '');
+  const m = /^---[ \t]*\n[\s\S]*?\n---[ \t]*(?:\n|$)/.exec(s);
+  if (!m) return { text: s, line: 1 };
+  return { text: s.slice(m[0].length), line: m[0].split('\n').length - (m[0].endsWith('\n') ? 1 : 0) + 1 };
+}
+
+// ── The description helper ──
+
+/** The description budgets of each runtime: characters used and allowed. Claude Code lists description and when_to_use together. */
+export function descriptionBudgets(data) {
+  const d = typeof data?.description === 'string' ? data.description : '';
+  const when = typeof data?.when_to_use === 'string' ? data.when_to_use : '';
+  const rows = [
+    { id: 'portable-six-field', runtime: 'portable', limit: PROFILES['portable-six-field'].limits.descriptionChars, used: d.length },
+    { id: 'claude-code', runtime: 'claude', limit: PROFILES['claude-code'].limits.listingChars, used: d.length + when.length, listing: true },
+    { id: 'codex-native', runtime: 'codex', limit: PROFILES['codex-native'].limits.descriptionChars, used: d.length },
+    { id: 'opencode-native', runtime: 'opencode', limit: PROFILES['opencode-native'].limits.descriptionChars, used: d.length },
+  ];
+  return rows.map((r) => ({ ...r, over: r.used > r.limit, ratio: r.limit ? Math.min(1, r.used / r.limit) : 0 }));
+}
+
+// Words that say when a skill applies (English and Portuguese), the cue a model reads to decide.
+const WHEN_CUES = [
+  /\buse (?:it |this(?: skill)? |me )?(?:when|whenever|for|if|to)\b/i,
+  /\bwhen(?:ever)? (?:the user|you|a user|someone|asked|working|preparing|writing|creating|editing|reviewing)\b/i,
+  /\btriggers? (?:on|when)\b/i,
+  /\b(?:invoke|apply|run) (?:it |this )?(?:when|whenever|for)\b/i,
+  /\bquando (?:o usuário|a usuária|você|alguém|for|precisar|pedir)\b/i,
+  /\buse (?:quando|para|se)\b/i,
+];
+
+/** Whether a description says when the skill applies (the cue a model reads to pick it). */
+export const describesWhen = (text) => WHEN_CUES.some((re) => re.test(String(text ?? '')));
+
+/** Whether a description says what the skill does: more than a few words of its own. */
+export function describesWhat(text) {
+  const words = String(text ?? '').trim().split(/\s+/).filter((w) => /[\p{L}\p{N}]/u.test(w));
+  return words.length >= 4;
+}
+
+/**
+ * What the description helper says: the budgets, and whether "what" and "when" are there.
+ * @returns {{ budgets: object[], what: boolean, when: boolean, empty: boolean, advice: 'ok'|'add-when'|'add-what'|'write-one'|'too-long' }}
+ */
+export function descriptionHelp(data) {
+  const text = typeof data?.description === 'string' ? data.description : '';
+  const budgets = descriptionBudgets(data);
+  const empty = !text.trim();
+  const what = !empty && describesWhat(text);
+  const when = !empty && (describesWhen(text) || (typeof data?.when_to_use === 'string' && data.when_to_use.trim() !== ''));
+  const advice = empty ? 'write-one' : budgets.some((b) => b.over) ? 'too-long' : !what ? 'add-what' : !when ? 'add-when' : 'ok';
+  return { budgets, what, when, empty, advice };
+}
+
+// ── Keys the form leaves alone ──
+
+/**
+ * The frontmatter keys the form has no field for, each with the lines it is written on: the Advanced section
+ * lists them so it is plain they are kept, byte for byte.
+ * @param {'skill'|'agent'|'command'} type
+ * @param {object} parsed ss-frontmatter.js parse()
+ * @param {string} text the document ("\n" line breaks)
+ */
+export function keptKeys(type, parsed, text) {
+  const known = new Set((FORM_FIELDS[type] || []).map((f) => f.key));
+  const keys = Array.isArray(parsed?.keys) ? parsed.keys : [];
+  const lines = String(text ?? '').split('\n');
+  const close = (() => {
+    if (!parsed?.hasFrontmatter) return 0;
+    for (let i = 1; i < lines.length; i++) if (/^---[ \t]*$/.test(lines[i])) return i + 1;   // 1-based line of the closing ---
+    return lines.length;
+  })();
+  const out = [];
+  keys.forEach((k, i) => {
+    if (known.has(k.key)) return;
+    const from = k.line;
+    const to = (keys[i + 1]?.line ?? close) - 1;
+    const body = lines.slice(from - 1, Math.max(from, to)).join('\n').replace(/\s+$/, '');
+    out.push({ key: k.key, line: from, kind: k.kind, text: body.length > 600 ? `${body.slice(0, 600)}…` : body });
+  });
+  return out;
+}
+
+/** The frontmatter block as written (for the YAML view), or '' when there is none. */
+export function frontmatterText(text) {
+  const s = String(text ?? '').replace(/^/, '');
+  const m = /^---[ \t]*\n([\s\S]*?)\n---[ \t]*(?:\n|$)/.exec(s);
+  return m ? m[1] : '';
+}
+
+/** A line and column (1-based) of a diagnostic, kept inside the document. */
+export function clampLine(line, text) {
+  const n = String(text ?? '').split('\n').length;
+  const l = Number.isInteger(line) && line > 0 ? line : 1;
+  return Math.min(l, n);
+}
+
+/** The short revision label of a digest (`sha256:abcdef…` → `abcdef1`), or ''. */
+export function shortDigest(digest) {
+  const m = /^sha256:([0-9a-f]{7,})/.exec(String(digest ?? ''));
+  return m ? m[1].slice(0, 7) : '';
+}

package/neural-interface/public/shared/skills/studio/sx-errors.js

@@ -0,0 +1,22 @@
+// Server failures are translated by code. Unknown codes remain useful diagnostics without leaking server prose.
+export function studioErrorText(t, error) {
+  const code = error?.code || error?.body?.code;
+  const keys = {
+    WORKER_BROWSER: 'workerBrowser', GUEST_FORBIDDEN: 'owner', UI_ONLY: 'owner', OWNER_REQUIRED: 'owner',
+    WORKERS_NOT_PERMITTED: 'owner', ASSISTANT_CREDENTIAL_REQUIRED: 'owner',
+    PAGE_SECRET_REQUIRED: 'pageSession', UI_HEADER_REQUIRED: 'pageSession',
+    revision_conflict: 'conflict', draft_conflict: 'conflict', etag_conflict: 'conflict',
+    revision_not_found: 'missing', artifact_not_found: 'missing', not_found: 'missing',
+    scan_incomplete: 'scanIncomplete', scan_blocked: 'scanBlocked', export_blocked: 'exportBlocked',
+    catalog_incomplete: 'catalogIncomplete', source_changed: 'sourceChanged', unsafe_source: 'unsafeSource',
+    export_review_required: 'exportReviewRequired', invalid_name: 'invalidName', invalid_format: 'invalidFormat',
+    invalid_profile: 'invalidProfile', export_transform_failed: 'exportTransformFailed',
+    blob_missing: 'revisionDamaged', blob_corrupt: 'revisionDamaged', revision_corrupt: 'revisionDamaged',
+    export_incompatible: 'exportIncompatible', invalid_frontmatter: 'invalidFrontmatter',
+    source_disabled: 'sourceDisabled', source_unavailable: 'sourceUnavailable',
+  };
+  const body = error?.body || error;
+  if (code === 'export_blocked' && body?.reason === 'lint') return t('skillsStudio.errors.exportLint', { detail: (body.diagnostics || []).slice(0, 5).map((d) => [d.file, d.line, d.message].filter(Boolean).join(': ')).join('; ') });
+  if (keys[code]) return t(`skillsStudio.errors.${keys[code]}`);
+  return t('skillsStudio.errors.request', { code: typeof code === 'string' && /^[a-zA-Z0-9_-]{1,80}$/.test(code) ? code : 'network' });
+}

package/neural-interface/public/shared/skills/studio/sx-geometry.js

@@ -0,0 +1,82 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: where the window is, and where a link takes it
+// ═══════════════════════════════════════════
+//
+// The window opens where it was left (the shared panel system saves a moved or resized window, ui-panels.js), at
+// min(1180px, 94% of the width) × min(760px, 86% of the height) the first time, and is kept inside the viewport
+// below the menu bar. It can be docked: then it fills the work area beside the side panels (like the code editor)
+// and leaves them usable. Its own width decides the layout (CSS container queries at 900 / 760 / 560 px):
+// the rail folds to icons, the editor shows one pane at a time, the Library's rows become cards.
+// A link into the Studio (`skills:open` with a detail) names a place, a skill, a review, a tab, a file and a line,
+// or an AI drafting (a creation) to follow in Create.
+// No DOM and no imports.
+
+export const DEFAULT_SIZE = Object.freeze({ width: 1180, height: 760, widthShare: 0.94, heightShare: 0.86 });
+export const MIN_SIZE = Object.freeze({ width: 380, height: 320 });
+export const LAYOUTS = Object.freeze([{ name: 'compact', max: 560 }, { name: 'narrow', max: 760 }, { name: 'medium', max: 900 }]);
+export const PLACES = Object.freeze(['library', 'review', 'create', 'discover', 'health']);
+export const TABS = Object.freeze(['edit', 'test', 'versions', 'publish']);
+
+const px = (v) => { const n = Number.parseFloat(v); return Number.isFinite(n) ? n : null; };
+
+/**
+ * The window's first rectangle: what was saved (kept inside the viewport), else the default size, centred.
+ * `frame` is the app frame's rect when the page has one (app-frame.js frameRect()): the window stays inside it, up to
+ * its edges. Without it, the window below the menu bar.
+ * @param {{ vw: number, vh: number, navbar?: number, saved?: { left?, top?, width?, height? } | null,
+ *   frame?: { left: number, top: number, right: number, bottom: number } | null }} o
+ */
+export function initialRect({ vw, vh, navbar = 48, saved = null, frame = null }) {
+  const b = frame || { left: 0, top: navbar, right: vw, bottom: vh };
+  const bw = b.right - b.left, bh = b.bottom - b.top;
+  const room = frame
+    ? { width: Math.max(MIN_SIZE.width, bw), height: Math.max(MIN_SIZE.height, bh) }
+    : { width: Math.max(MIN_SIZE.width, vw - 20), height: Math.max(MIN_SIZE.height, vh - navbar - 10) };
+  let width = px(saved?.width) ?? Math.min(DEFAULT_SIZE.width, Math.round((frame ? bw : vw) * DEFAULT_SIZE.widthShare));
+  let height = px(saved?.height) ?? Math.min(DEFAULT_SIZE.height, Math.round((frame ? bh : vh) * DEFAULT_SIZE.heightShare));
+  width = Math.round(Math.max(MIN_SIZE.width, Math.min(width, room.width)));
+  height = Math.round(Math.max(MIN_SIZE.height, Math.min(height, room.height)));
+  let left = px(saved?.left);
+  let top = px(saved?.top);
+  if (left === null) left = Math.round(b.left + (bw - width) / 2);
+  if (top === null) top = Math.round(b.top + Math.max(0, (bh - height) / 2));
+  left = Math.round(Math.max(b.left, Math.min(left, b.right - width)));
+  top = Math.round(Math.max(b.top, Math.min(top, b.bottom - height)));
+  return { left, top, width, height };
+}
+
+/** The layout a width of the window gets (the same thresholds as the CSS container queries). */
+export function layoutOf(width) {
+  for (const l of LAYOUTS) if (width <= l.max) return l.name;
+  return 'wide';
+}
+
+/**
+ * A link into the Studio, normalised: unknown values fall back, ids are kept only when they have their shape.
+ * @param {object} detail what `skills:open` carried
+ * @returns {{ place: string, tab: string|null, skillId: string|null, artifactId: string|null, reviewId: string|null,
+ *   name: string|null, file: string|null, line: number|null, create: string|null, creationId: string|null }}
+ */
+export function parseOpen(detail) {
+  const d = detail && typeof detail === 'object' ? detail : {};
+  const shaped = (v, re) => (typeof v === 'string' && re.test(v) ? v : null);
+  const out = {
+    place: PLACES.includes(d.place) ? d.place : null,
+    tab: TABS.includes(d.tab) ? d.tab : null,
+    skillId: shaped(d.skillId, /^skl_[0-9a-f]{20}$/),
+    artifactId: shaped(d.artifactId, /^art_[0-9a-f]{20}$/),
+    reviewId: shaped(d.reviewId, /^rvw_[0-9a-f]{20}$/),
+    name: typeof d.name === 'string' && d.name.length <= 128 && !/[\\/]/.test(d.name) ? d.name : null,
+    file: typeof d.file === 'string' && d.file.length <= 512 && !d.file.split('/').includes('..') && !d.file.startsWith('/') ? d.file : null,
+    line: Number.isInteger(d.line) && d.line > 0 ? d.line : null,
+    create: d.create === 'blank' || d.create === 'import' ? d.create : null,
+    creationId: shaped(d.creationId, /^crt_[0-9a-f]{20}$/),
+  };
+  if (!out.place) out.place = out.reviewId ? 'review' : (out.create || out.creationId) ? 'create' : 'library';
+  return out;
+}
+
+/** The keys of the Studio (also the help it shows): ⌘/Ctrl on a Mac or not. */
+export function shortcutLabel(key, mac) {
+  return key.replace(/Mod/g, mac ? '⌘' : 'Ctrl').replace(/Alt/g, mac ? '⌥' : 'Alt').replace(/Shift/g, mac ? '⇧' : 'Shift').replace(/Enter/g, mac ? '↵' : 'Enter').replace(/\+/g, mac ? '' : '+');
+}

package/neural-interface/public/shared/skills/studio/sx-import.js

@@ -0,0 +1,262 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio 2.0: importing a bundle
+// ═══════════════════════════════════════════
+//
+// A bundle is checked and staged by the server first, outside every folder a runtime reads skills from (nothing of
+// it runs or loads there), and scanned. The owner sees what it is and what it can do, then installs exactly those
+// bytes (the staged digest), or discards it. The scope is the one they pick: global, or a project they choose;
+// never a default. Files already there are replaced only when the owner ticks the box (a backup is kept). A file
+// is picked in the click that asked for it (the browser's rule); what the server can do is asked once it is chosen.
+
+import { studioErrorText } from './sx-errors.js';
+import { dropdownHTML, wireDropdowns } from '../../cc-dropdown.js';
+import { revealHidden } from '../ss-unicode.js';
+import { decodeArtifactId } from '../ss-ids.js';
+
+const SEVERITY_MARK = { critical: '⛔', high: '✕', medium: '⚠', low: '•', info: '•' };
+const MAX_BUNDLE_BYTES = 24 * 1024 * 1024;
+
+const el = (tag, cls, text) => { const n = document.createElement(tag); if (cls) n.className = cls; if (text !== undefined) n.textContent = text; return n; };
+
+/**
+ * Pick a bundle and import it.
+ * @param {object} ctx the Studio's context
+ * @param {() => Promise<Set<string>>} capabilities what the server can do, once known
+ */
+export function triggerImport(ctx, capabilities) {
+  if (ctx.guest) { ctx.toast(ctx.t('skillsStudio.import.guest'), 'error'); return; }
+  const input = document.createElement('input');
+  input.type = 'file';
+  input.accept = BUNDLE_ACCEPT;
+  input.addEventListener('change', () => { const file = input.files?.[0]; if (file) importFile(ctx, file, capabilities); });
+  input.click();
+}
+
+/** The file types the picker offers. */
+export const BUNDLE_ACCEPT = '.json,.skill.json,.command.json,.agent.json';
+
+/** A bundle file someone picked (here, or from the menu before the Studio was loaded): read, checked, imported. */
+export async function importFile(ctx, file, capabilities) {
+  const { t } = ctx;
+  if (ctx.guest) { ctx.toast(t('skillsStudio.import.guest'), 'error'); return; }
+  try { await capabilities(); } catch { ctx.toast(t('skillsStudio.import.serverUnknown'), 'error'); return; }
+  if (file.size > MAX_BUNDLE_BYTES) { ctx.toast(t('skillsStudio.import.tooLarge'), 'error'); return; }
+  let bundle;
+  try { bundle = JSON.parse(await file.text()); } catch { ctx.toast(t('skillsStudio.import.notJson'), 'error'); return; }
+  if (!bundle || bundle.format !== 'synabun-skill-bundle') { ctx.toast(t('skillsStudio.import.notBundle'), 'error'); return; }
+  if (ctx.panel?.isConnected) await runImport(ctx, bundle, file.name);
+}
+
+function scopePicker(ctx, prefix) {
+  const { t } = ctx;
+  const projects = [{ value: '', label: t('skillsStudio.import.chooseProject'), disabled: true, selected: true }, ...ctx.projects.map((p) => ({ value: p.path, label: p.label }))];
+  const wrap = el('div', 'sx-dlg-form');
+  const group = el('div', 'sx-choices');
+  group.setAttribute('role', 'radiogroup');
+  group.setAttribute('aria-label', t('skillsStudio.import.where'));
+  for (const [value, words] of [['global', t('skillsStudio.import.scopeGlobal')], ['project', t('skillsStudio.import.scopeProject')]]) {
+    const label = el('label', 'sx-choice');
+    const radio = el('input');
+    radio.type = 'radio';
+    radio.name = `${prefix}-scope`;
+    radio.value = value;
+    if (value === 'global') radio.checked = true;
+    if (value === 'project' && !ctx.projects.length) radio.disabled = true;
+    label.append(radio, document.createTextNode(` ${words}`));
+    group.append(label);
+  }
+  const field = el('div', 'sx-field');
+  field.hidden = true;
+  field.id = `${prefix}-project-field`;
+  const fieldLabel = el('span', 'sx-field-label', t('skillsStudio.import.project'));
+  fieldLabel.id = `${prefix}-project-label`;
+  const dd = el('div');
+  dd.innerHTML = dropdownHTML(`${prefix}-project`, projects, { labelledBy: `${prefix}-project-label` });
+  field.append(fieldLabel, ...dd.childNodes);
+  const error = el('p', 'ss-dlg-error');
+  error.id = `${prefix}-error`;
+  error.setAttribute('role', 'alert');
+  wrap.append(group, field, error);
+  return wrap;
+}
+
+/** Where it goes, staged and scanned, the owner's review, then exactly those bytes installed (or nothing). */
+export async function runImport(ctx, bundle, fileName) {
+  const { t, tp, api } = ctx;
+  const type = ['skill', 'command', 'agent'].includes(bundle.type) ? bundle.type : 'skill';
+  const files = bundle.files && typeof bundle.files === 'object' ? Object.keys(bundle.files).length : 0;
+  // 1. Where it goes.
+  const life = new AbortController();
+  const extra = scopePicker(ctx, 'ss-imp');
+  wireDropdowns(extra, { signal: life.signal });
+  extra.addEventListener('change', (e) => { if (e.target.name === 'ss-imp-scope') extra.querySelector('#ss-imp-project-field').hidden = e.target.value !== 'project'; }, { signal: life.signal });
+  let place = null;
+  const where = await ctx.ask({
+    title: t('skillsStudio.import.title', { kind: t(`skillsStudio.kind.${type}`), name: revealHidden(String(bundle.name ?? '')) }),
+    lines: [tp('skillsStudio.import.intro', files, { file: fileName })],
+    extra,
+    buttons: [{ id: 'cancel', label: t('skillsStudio.dialog.cancel') }, { id: 'check', label: t('skillsStudio.import.check'), kind: 'primary' }],
+    accept: () => {
+      const scope = extra.querySelector('input[name="ss-imp-scope"]:checked')?.value || 'global';
+      const projectPath = scope === 'project' ? (extra.querySelector('#ss-imp-project')?.value || '') : '';
+      const error = scope === 'project' && !projectPath ? t('skillsStudio.import.chooseProjectError') : '';
+      extra.querySelector('#ss-imp-error').textContent = error;
+      if (error) return false;
+      place = { scope, projectPath };
+      return true;
+    },
+  });
+  life.abort();
+  if (where !== 'check' || !place || !ctx.panel?.isConnected) return;
+
+  // 2. Staged and scanned by the server.
+  let staged;
+  try {
+    staged = (await api.stageSkillsImport(bundle, place.scope, place.projectPath)).staged;
+  } catch (err) {
+    const problems = Array.isArray(err?.body?.problems) ? err.body.problems : [];
+    if (problems.length && ctx.panel?.isConnected) {
+      await ctx.ask({
+        title: t('skillsStudio.import.refusedTitle'),
+        lines: [t('skillsStudio.import.refusedIntro'), ...problems.slice(0, 12).map((p) => `• ${p.path ? `${revealHidden(p.path)}: ` : ''}${p.message}`), problems.length > 12 ? `• ${t('skillsStudio.dialog.andMore', { count: problems.length - 12 })}` : ''],
+        buttons: [{ id: 'cancel', label: t('skillsStudio.dialog.close'), kind: 'primary' }],
+      });
+    } else ctx.toast(t('skillsStudio.import.failed', { error: studioErrorText(ctx.t, err) }), 'error');
+    return;
+  }
+  if (!ctx.panel?.isConnected) { api.discardSkillsImport(staged.stagingId).catch(() => {}); return; }
+
+  // 3. The review: what it is, what it can do, what it would replace.
+  const review = buildImportReview(ctx, staged);
+  const lintErrors = staged.lint?.errors || 0;
+  const skillExists = staged.type === 'skill' && staged.collisions?.length > 0;
+  const blocked = staged.scan?.gate === 'blocked';
+  const answer = await ctx.ask({
+    wide: true,
+    title: t('skillsStudio.import.reviewTitle', { name: revealHidden(staged.name) }),
+    lines: [],
+    extra: review,
+    buttons: [{ id: 'discard', label: t('skillsStudio.import.discard'), kind: 'danger' }, { id: 'install', label: t('skillsStudio.import.install'), kind: 'primary', disabled: !!(lintErrors || skillExists || blocked) }],
+    focus: 'discard',
+    cancelId: 'discard',
+    accept: (choice) => {
+      if (choice !== 'install') return true;
+      const ack = review.querySelector('#ss-imp-ack');
+      const over = review.querySelector('#ss-imp-overwrite');
+      const error = ack && !ack.checked ? t('skillsStudio.import.confirmReviewed') : over && !over.checked ? t('skillsStudio.import.confirmReplace') : '';
+      const line = review.querySelector('#ss-imp-review-error');
+      if (line) line.textContent = error;
+      return !error;
+    },
+  });
+  if (answer !== 'install') { api.discardSkillsImport(staged.stagingId).catch(() => {}); return; }
+
+  // 4. Installed: exactly the staged bytes, or nothing.
+  try {
+    const res = await api.commitSkillsImport({
+      stagingId: staged.stagingId, expectedDigest: staged.digest,
+      acknowledgedDigest: staged.scan?.gate === 'review' ? staged.digest : undefined,
+      overwrite: !!review.querySelector('#ss-imp-overwrite')?.checked,
+    });
+    ctx.toast(t('skillsStudio.import.done', { name: res.name }));
+    await ctx.reload();
+    const id = decodeArtifactId(res.id);
+    const path = id.slice(id.indexOf(':') + 1);
+    const row = ctx.rows.find((r) => r.entries.some((e) => e.path === path));
+    if (row && ctx.panel?.isConnected) ctx.openRow(row.key, { tab: 'edit' });
+  } catch (err) {
+    ctx.toast(t('skillsStudio.import.failed', { error: studioErrorText(ctx.t, err) }), 'error');
+  }
+}
+
+/** The review of a staged import, built as text nodes: nothing of the bundle is ever markup here. */
+export function buildImportReview(ctx, staged) {
+  const { t, tp } = ctx;
+  const root = el('div', 'ss-review');
+  const row = (label, value, mono = false) => {
+    const r = el('div', 'ss-review-row');
+    r.append(el('span', 'ss-review-label', label), el(mono ? 'code' : 'span', 'ss-review-value', value));
+    root.append(r);
+  };
+  const size = (staged.files || []).reduce((n, f) => n + (Number(f.size) || 0), 0);
+  row(t('skillsStudio.import.goesTo'), staged.destination, true);
+  row(t('skillsStudio.import.files'), tp('skillsStudio.import.fileCount', staged.files?.length || 0, { size: size > 1024 ? `${Math.round(size / 1024)} KB` : `${size} B` }));
+  row(t('skillsStudio.import.digest'), staged.digest ? `${staged.digest.slice(0, 19)}…${staged.digest.slice(-6)}` : '', true);
+  const fileList = el('details', 'ss-review-files');
+  fileList.append(el('summary', '', t('skillsStudio.import.showFiles')));
+  const ul = el('ul');
+  for (const f of staged.files || []) ul.append(el('li', '', `${revealHidden(f.path)}${f.executable ? ` (${t('skillsStudio.import.executable')})` : ''}`));
+  for (const x of staged.excluded || []) ul.append(el('li', 'ss-review-muted', t('skillsStudio.import.leftOut', { path: revealHidden(x.path), reason: x.reason })));
+  fileList.append(ul);
+  root.append(fileList);
+
+  if (staged.type === 'skill' && staged.collisions?.length) root.append(el('p', 'ss-review-warn', t('skillsStudio.import.skillExists', { name: staged.name })));
+  if (staged.type !== 'skill' && staged.collisions?.length) {
+    const label = el('label', 'ss-review-check');
+    const box = el('input');
+    box.type = 'checkbox';
+    box.id = 'ss-imp-overwrite';
+    label.append(box, document.createTextNode(` ${tp('skillsStudio.import.replaceBox', staged.collisions.length, { files: staged.collisions.join(', ') })}`));
+    root.append(label);
+  }
+
+  // Checks of the head file
+  const lint = staged.lint || { diagnostics: [] };
+  const shownLint = (lint.diagnostics || []).filter((d) => d.severity !== 'info');
+  const checks = el('div', 'ss-review-section');
+  checks.append(el('div', 'ss-review-head', shownLint.length ? t('skillsStudio.import.checks', { errors: lint.errors || 0, warnings: lint.warnings || 0 }) : t('skillsStudio.import.checksOk')));
+  if (shownLint.length) {
+    const list = el('ul', 'ss-review-list');
+    for (const d of shownLint.slice(0, 20)) list.append(el('li', `ss-review-item ss-review-item--${d.severity === 'error' ? 'high' : 'medium'}`, `${d.message}${d.line ? ` (${t('skillsStudio.edit.line', { line: d.line })})` : ''}`));
+    checks.append(list);
+  }
+  if (lint.errors) checks.append(el('p', 'ss-review-warn', t('skillsStudio.import.blockedByProblems')));
+  root.append(checks);
+
+  // What it can do
+  const scan = staged.scan || {};
+  const auth = scan.authority || {};
+  const section = el('div', 'ss-review-section');
+  const found = scan.findings?.length || 0;
+  const status = scan.status === 'no_findings' ? t('skillsStudio.import.scanClean')
+    : scan.status === 'error' ? t('skillsStudio.import.scanError', { error: scan.error || 'error' })
+    : scan.status === 'incomplete' ? tp('skillsStudio.import.scanIncomplete', found)
+    : tp('skillsStudio.import.scanFindings', found);
+  section.append(el('div', 'ss-review-head', `${t('skillsStudio.import.canDo')} ${status}${scan.gate === 'blocked' ? ` (${t('skillsStudio.import.gateBlocked')})` : scan.gate === 'review' ? ` (${t('skillsStudio.import.gateReview')})` : ''}`));
+  const facts = [];
+  if (auth.dynamicContext?.length) facts.push(tp('skillsStudio.import.fact.dynamic', auth.dynamicContext.length));
+  if (auth.hooks?.length) facts.push(t('skillsStudio.import.fact.hooks', { events: auth.hooks.map((h) => h.event).join(', ') }));
+  if (auth.toolGrants?.length) facts.push(t('skillsStudio.import.fact.tools', { tools: auth.toolGrants.map((g) => g.tool).join(', ') }));
+  if (auth.scripts?.length) facts.push(tp('skillsStudio.import.fact.scripts', auth.scripts.length));
+  if (auth.binaries?.length) facts.push(tp('skillsStudio.import.fact.binaries', auth.binaries.length));
+  if (auth.domains?.length) facts.push(t('skillsStudio.import.fact.domains', { domains: auth.domains.slice(0, 6).join(', ') + (auth.domains.length > 6 ? ` +${auth.domains.length - 6}` : '') }));
+  if (facts.length) { const ul2 = el('ul', 'ss-review-facts'); for (const f of facts) ul2.append(el('li', '', f)); section.append(ul2); }
+  if (scan.findings?.length) {
+    const list = el('ul', 'ss-review-list');
+    for (const f of scan.findings.slice(0, 30)) {
+      const li = el('li', `ss-review-item ss-review-item--${f.severity}`);
+      li.append(el('span', 'ss-review-sev', `${SEVERITY_MARK[f.severity] || '•'} ${t(`skillsStudio.review.severity.${['critical', 'high', 'medium', 'low'].includes(f.severity) ? f.severity : 'low'}`)}`), el('span', '', ` ${f.message}`));
+      if (f.file) li.append(el('span', 'ss-review-where', ` ${revealHidden(f.file)}${f.line ? `:${f.line}` : ''}`));
+      if (f.evidence) li.append(el('code', 'ss-review-evidence', f.evidence));
+      list.append(li);
+    }
+    if (scan.findings.length > 30) list.append(el('li', 'ss-review-muted', t('skillsStudio.dialog.andMore', { count: scan.findings.length - 30 })));
+    section.append(list);
+  }
+  if (scan.disclosure) section.append(el('p', 'ss-review-muted', scan.disclosure));
+  root.append(section);
+
+  if (scan.gate === 'review') {
+    const label = el('label', 'ss-review-check');
+    const box = el('input');
+    box.type = 'checkbox';
+    box.id = 'ss-imp-ack';
+    label.append(box, document.createTextNode(` ${t('skillsStudio.import.reviewedBox')}`));
+    root.append(label);
+  }
+  const err = el('p', 'ss-dlg-error', '');
+  err.id = 'ss-imp-review-error';
+  err.setAttribute('role', 'alert');
+  root.append(err);
+  return root;
+}