synabun 2.0.10 → 2.2.0

package/neural-interface/public/shared/skills/ss-frontmatter.js

@@ -0,0 +1,376 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio: the frontmatter of a skill, a command or an agent
+// ═══════════════════════════════════════════
+//
+// A skill's metadata is YAML between two `---` lines at the top of its file. It is read here with a real YAML
+// parser (the `yaml` package), and changed one key at a time: an edit replaces the text of that one key and
+// nothing else, so every key the edit does not touch keeps its bytes (order, quoting, folding, comments, keys
+// no form knows). A change is checked by reading the result again before it is handed back: the key holds the
+// new value, every other key what it held, or the change is refused and the text stays as it was.
+//
+// What is not plain YAML is said, never guessed: a syntax error, a key given twice, a root that is not a
+// mapping, an alias, a tag the parser does not resolve. While the YAML has errors nothing is patched: the
+// form waits, the raw text is still editable and saveable.
+//
+// No imports: the YAML library is handed in (the server gives it the `yaml` package, the page the copy in
+// /vendor/yaml/), so `node --test` loads this module as it is.
+
+/** A frontmatter longer than this is not parsed (a bound on what one request makes the parser do). */
+export const FRONTMATTER_MAX_CHARS = 128 * 1024;
+/** Aliases a document may expand while it is read (the `yaml` package's guard against alias bombs). */
+export const MAX_ALIAS_COUNT = 100;
+
+export const PARSE_OPTIONS = Object.freeze({
+  uniqueKeys: true,          // a key given twice is an error, not "the last one wins"
+  strict: true,
+  prettyErrors: true,        // line and column on every error
+  resolveKnownTags: false,   // !!binary, !!set, !!omap… stay unresolved (a warning), never other types
+  merge: false,              // `<<` is a key like any other
+  keepSourceTokens: false,
+});
+
+const BREAK = /\r\n|\n|\r/g;
+
+/** The line ending at `index`: its length (0 at the end of the text). */
+function breakAt(text, index) {
+  if (text.charCodeAt(index) === 13) return text.charCodeAt(index + 1) === 10 ? 2 : 1;
+  if (text.charCodeAt(index) === 10) return 1;
+  return 0;
+}
+
+/** The index of the next line break at or after `from` (the text's length when there is none). */
+function nextBreak(text, from) {
+  for (let i = from; i < text.length; i++) {
+    const c = text.charCodeAt(i);
+    if (c === 10 || c === 13) return i;
+  }
+  return text.length;
+}
+
+/** 1-based line number of an index in a text. */
+export function lineOfIndex(text, index) {
+  let line = 1;
+  const s = String(text ?? '');
+  BREAK.lastIndex = 0;
+  let m;
+  while ((m = BREAK.exec(s)) && m.index < index) line++;
+  return line;
+}
+
+/**
+ * Where the frontmatter is. It opens with a first line `---` (after a byte-order mark, if any) and closes at the
+ * next line that is `---`; trailing blanks on either line are allowed.
+ * @returns {{ bom: boolean, hasFrontmatter: boolean, unterminated: boolean, yamlStart: number, yamlEnd: number,
+ *   bodyStart: number, yaml: string, body: string, startLine: number }} `yaml` is the text between the two lines
+ *   (with the line ending of its last line), `startLine` the line it starts on (1-based), `bodyStart` where the
+ *   text after the closing line starts.
+ */
+export function splitFrontmatter(text) {
+  const s = String(text ?? '');
+  const bom = s.charCodeAt(0) === 0xFEFF;
+  const at = bom ? 1 : 0;
+  const none = (unterminated = false) => ({
+    bom, hasFrontmatter: false, unterminated, yamlStart: at, yamlEnd: at, bodyStart: at, yaml: '', body: s.slice(at), startLine: 1,
+  });
+  const firstEnd = nextBreak(s, at);
+  if (!/^---[ \t]*$/.test(s.slice(at, firstEnd)) || firstEnd >= s.length) return none(false);
+  const yamlStart = firstEnd + breakAt(s, firstEnd);
+  let line = yamlStart;
+  while (line <= s.length) {
+    const end = nextBreak(s, line);
+    if (/^---[ \t]*$/.test(s.slice(line, end))) {
+      const bodyStart = end + breakAt(s, end);
+      return {
+        bom, hasFrontmatter: true, unterminated: false, yamlStart, yamlEnd: line, bodyStart,
+        yaml: s.slice(yamlStart, line), body: s.slice(bodyStart), startLine: 2,
+      };
+    }
+    if (end >= s.length) break;
+    line = end + breakAt(s, end);
+  }
+  return none(true);
+}
+
+/** What kind of value a frontmatter key holds, for a form that shows only what it can write back. */
+export function valueKind(value) {
+  if (value === undefined) return 'absent';
+  if (value === null) return 'null';
+  if (typeof value === 'string') return 'string';
+  if (typeof value === 'boolean') return 'boolean';
+  if (typeof value === 'number') return Number.isFinite(value) ? 'number' : 'other';
+  if (Array.isArray(value)) return value.every((v) => typeof v === 'string') ? 'string-list' : 'list';
+  return 'other';
+}
+
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return Number.isNaN(a) && Number.isNaN(b);
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a); const kb = Object.keys(b);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k, i) => k === kb[i] && deepEqual(a[k], b[k]));
+}
+
+/** A copy of `data` whose keys are own data properties of objects without a prototype chain to reach. */
+function plainCopy(value, depth = 0) {
+  if (depth > 64) return null;
+  if (Array.isArray(value)) return value.map((v) => plainCopy(v, depth + 1));
+  if (value && typeof value === 'object') {
+    if (typeof value.length === 'number' && typeof value.BYTES_PER_ELEMENT === 'number') return null;   // typed arrays: not a skill value
+    const out = Object.create(null);
+    for (const key of Object.keys(value)) out[key] = plainCopy(value[key], depth + 1);
+    return out;
+  }
+  return value;
+}
+
+/**
+ * The frontmatter tools over one YAML library.
+ * @param {object} YAML the `yaml` package (parseDocument, Document, isMap, isScalar, isSeq, isCollection, isAlias, visit)
+ */
+export function createFrontmatter(YAML) {
+  const diag = (ruleId, severity, message, line = null, column = null) => ({ ruleId, severity, message, line, column });
+
+  function fromYamlError(err, severity, startLine) {
+    const pos = Array.isArray(err?.linePos) ? err.linePos[0] : null;
+    const first = String(err?.message || 'YAML error').split('\n')[0].replace(/ at line \d+, column \d+:?$/, '');
+    const code = String(err?.code || '').toLowerCase().replace(/_/g, '-');
+    const ruleId = code === 'duplicate-key' ? 'yaml-duplicate-key' : (code === 'tag-resolve-failed' ? 'yaml-tag' : 'yaml-syntax');
+    return diag(ruleId, severity, first, pos ? pos.line + startLine - 1 : startLine, pos ? pos.col : null);
+  }
+
+  function parseYaml(yaml) {
+    return YAML.parseDocument(yaml, PARSE_OPTIONS);
+  }
+
+  const keyName = (pair) => (YAML.isScalar(pair?.key) && typeof pair.key.value === 'string' ? pair.key.value : null);
+
+  /**
+   * Read a document's frontmatter.
+   * @param {string} text the whole file (a byte-order mark and any line ending are fine)
+   * @returns {{ hasFrontmatter: boolean, data: object | null, diagnostics: object[], keys: object[],
+   *   editable: boolean, body: string, bodyLine: number, split: object }} `data` is null when the YAML cannot
+   *   be read as a mapping; `editable` says whether patch() may change it; `keys` lists the top-level keys in
+   *   order: `{ key, line, kind, style, flow }`.
+   */
+  function parse(text) {
+    const s = String(text ?? '');
+    const split = splitFrontmatter(s);
+    const result = {
+      hasFrontmatter: split.hasFrontmatter, data: null, diagnostics: [], keys: [], editable: false,
+      body: split.hasFrontmatter ? split.body : s.slice(split.bom ? 1 : 0),
+      bodyLine: split.hasFrontmatter ? lineOfIndex(s, split.bodyStart) : 1,
+      split,
+    };
+    if (!split.hasFrontmatter) {
+      if (split.unterminated) result.diagnostics.push(diag('yaml-unterminated', 'error', 'The frontmatter opens with --- but no line closes it with ---.', 1));
+      result.data = Object.create(null);
+      result.editable = !split.unterminated;
+      return result;
+    }
+    if (split.yaml.length > FRONTMATTER_MAX_CHARS) {
+      result.diagnostics.push(diag('yaml-too-large', 'error', `The frontmatter is longer than ${Math.round(FRONTMATTER_MAX_CHARS / 1024)} KB and was not read.`, split.startLine));
+      return result;
+    }
+    let doc;
+    try { doc = parseYaml(split.yaml); } catch (err) {
+      result.diagnostics.push(diag('yaml-syntax', 'error', String(err?.message || 'The frontmatter could not be read.').split('\n')[0], split.startLine));
+      return result;
+    }
+    for (const err of doc.errors) result.diagnostics.push(fromYamlError(err, 'error', split.startLine));
+    for (const warn of doc.warnings) result.diagnostics.push(fromYamlError(warn, 'warning', split.startLine));
+    const root = doc.contents;
+    if (root === null || root === undefined) {
+      result.data = Object.create(null);
+      result.editable = doc.errors.length === 0;
+      return result;
+    }
+    if (!YAML.isMap(root)) {
+      result.diagnostics.push(diag('yaml-not-mapping', 'error', 'The frontmatter must be key: value lines (a YAML mapping).', split.startLine));
+      return result;
+    }
+    // YAML with errors is not read as data at all: what a parser makes of it is a guess, and no value of it is
+    // shown or checked as if it were what the file says.
+    if (doc.errors.length) return result;
+    let aliases = 0;
+    YAML.visit(doc, { Alias() { aliases++; } });
+    if (aliases) result.diagnostics.push(diag('yaml-alias', 'warning', `The frontmatter uses ${aliases === 1 ? 'an alias' : `${aliases} aliases`} (*name); the form leaves aliased values alone.`, split.startLine));
+    let data;
+    try { data = doc.toJS({ maxAliasCount: MAX_ALIAS_COUNT }); } catch (err) {
+      result.diagnostics.push(diag('yaml-alias-limit', 'error', String(err?.message || 'Too many aliases.').split('\n')[0], split.startLine));
+      return result;
+    }
+    result.data = plainCopy(data && typeof data === 'object' && !Array.isArray(data) ? data : {});
+    let complexKeys = 0;
+    for (const pair of root.items) {
+      const key = keyName(pair);
+      if (key === null) { complexKeys++; continue; }
+      const value = pair.value;
+      const start = pair.key.range?.[0] ?? 0;
+      result.keys.push({
+        key,
+        line: lineOfIndex(split.yaml, start) + split.startLine - 1,
+        kind: valueKind(result.data[key]),
+        style: YAML.isScalar(value) ? (value.type || null) : (YAML.isCollection(value) ? (value.flow ? 'flow' : 'block') : (YAML.isAlias(value) ? 'alias' : null)),
+        alias: YAML.isAlias(value),
+      });
+    }
+    if (complexKeys) result.diagnostics.push(diag('yaml-complex-key', 'warning', 'A key of the frontmatter is not plain text; the form leaves the frontmatter alone.', split.startLine));
+    result.editable = doc.errors.length === 0 && !root.flow && !complexKeys;
+    return result;
+  }
+
+  // ── Patching ──
+
+  /** How the value a key holds is written, so its new value is written the same way. */
+  function styleOf(yamlText, pair) {
+    const value = pair.value;
+    const style = { type: null, flow: undefined, indentSeq: true, indent: 2 };
+    if (YAML.isScalar(value)) style.type = value.type || null;
+    if (YAML.isCollection(value)) {
+      style.flow = !!value.flow;
+      if (!value.flow && value.range) {
+        const at = value.range[0];
+        const lineStart = yamlText.lastIndexOf('\n', at - 1) + 1;
+        const column = at - lineStart;
+        if (YAML.isSeq(value)) { style.indentSeq = column > 0; if (column > 0) style.indent = column; }
+        else if (column > 0) style.indent = column;
+      }
+    }
+    if (YAML.isScalar(value) && (value.type === 'BLOCK_FOLDED' || value.type === 'BLOCK_LITERAL') && value.range) {
+      // The indentation of the block's first line with text.
+      const block = yamlText.slice(value.range[0], value.range[1]);
+      const m = /\n( +)\S/.exec(block);
+      if (m) style.indent = Math.max(1, Math.min(8, m[1].length));
+    }
+    return style;
+  }
+
+  /** `key: value` as YAML, written in `style` where the value allows it. Ends with "\n". */
+  function serializePair(key, value, style = {}) {
+    const doc = new YAML.Document();
+    doc.contents = doc.createNode({ [key]: value });
+    const node = doc.contents.items[0].value;
+    if (style.type && YAML.isScalar(node) && typeof value === 'string') node.type = style.type;
+    if (style.flow !== undefined && YAML.isCollection(node)) node.flow = style.flow;
+    return doc.toString({
+      lineWidth: style.type === 'BLOCK_FOLDED' ? 80 : 0,
+      minContentWidth: 0,
+      indent: style.indent || 2,
+      indentSeq: style.indentSeq !== false,
+      flowCollectionPadding: false,
+    });
+  }
+
+  function findPair(root, key) {
+    if (!root || !YAML.isMap(root)) return null;
+    return root.items.find((pair) => keyName(pair) === key) || null;
+  }
+
+  // The text a pair spans: from the start of its key to the end of its value (a value written over several lines
+  // takes its last line ending with it). A comment after a one-line value is outside it, and stays.
+  function pairSpan(yamlText, pair) {
+    const start = pair.key.range[0];
+    const lineStart = yamlText.lastIndexOf('\n', start - 1) + 1;
+    if (yamlText.slice(lineStart, start).trim() !== '') return null;   // the key is not at the start of its line
+    let end;
+    if (pair.value && pair.value.range) end = pair.value.range[1];
+    else {
+      const colon = yamlText.indexOf(':', pair.key.range[1]);
+      if (colon < 0) return null;
+      end = colon + 1;
+    }
+    return { start, end, lineStart, block: yamlText.charCodeAt(end - 1) === 10 };
+  }
+
+  // The whole lines a pair takes: what removing the key removes. A comment on its last line goes with it.
+  function pairLines(yamlText, pair) {
+    const span = pairSpan(yamlText, pair);
+    if (!span) return null;
+    let end = span.block ? span.end : Math.max(span.end, pair.value?.range?.[2] ?? span.end);
+    if (yamlText.charCodeAt(end - 1) !== 10) {
+      const nl = yamlText.indexOf('\n', end);
+      const rest = yamlText.slice(end, nl < 0 ? yamlText.length : nl);
+      if (rest.trim() !== '' && !rest.trim().startsWith('#')) return null;
+      end = nl < 0 ? yamlText.length : nl + 1;
+    }
+    return { start: span.lineStart, end };
+  }
+
+  function patchOne(text, key, value) {
+    const split = splitFrontmatter(text);
+    const lead = split.bom ? '' : '';
+    if (!split.hasFrontmatter) {
+      if (split.unterminated) return { ok: false, reason: 'unterminated' };
+      if (value === undefined) return { ok: true, text };
+      const pairText = serializePair(key, value);
+      return { ok: true, text: `${lead}---\n${pairText}---\n${text.slice(split.bom ? 1 : 0)}` };
+    }
+    const yamlText = split.yaml;
+    let doc;
+    try { doc = parseYaml(yamlText); } catch { return { ok: false, reason: 'invalid' }; }
+    if (doc.errors.length) return { ok: false, reason: 'invalid' };
+    const root = doc.contents;
+    if (root !== null && root !== undefined && (!YAML.isMap(root) || root.flow)) return { ok: false, reason: 'unsupported' };
+    if (root && root.items.some((pair) => keyName(pair) === null)) return { ok: false, reason: 'unsupported' };
+    const pair = findPair(root, key);
+    if (pair && YAML.isAlias(pair.value)) return { ok: false, reason: 'alias' };
+    let next;
+    if (value === undefined) {
+      if (!pair) return { ok: true, text };
+      const lines = pairLines(yamlText, pair);
+      if (!lines) return { ok: false, reason: 'unsupported' };
+      next = yamlText.slice(0, lines.start) + yamlText.slice(lines.end);
+    } else if (pair) {
+      const span = pairSpan(yamlText, pair);
+      if (!span) return { ok: false, reason: 'unsupported' };
+      let replacement = serializePair(key, value, styleOf(yamlText, pair));
+      if (!span.block) replacement = replacement.replace(/\n$/, '');
+      next = yamlText.slice(0, span.start) + replacement + yamlText.slice(span.end);
+    } else {
+      const base = yamlText === '' || yamlText.endsWith('\n') ? yamlText : `${yamlText}\n`;
+      next = base + serializePair(key, value);
+    }
+    return { ok: true, text: text.slice(0, split.yamlStart) + next + text.slice(split.yamlEnd) };
+  }
+
+  /**
+   * Change keys of a document's frontmatter, each by its own text, and check the result.
+   * @param {string} text the whole document
+   * @param {Record<string, any>} changes key → new value; `undefined` removes the key
+   * @returns {{ ok: true, text: string, changed: boolean } | { ok: false, text: string, reason: string, key: string }}
+   *   `reason`: `invalid` (the YAML has errors), `unterminated`, `unsupported` (a layout this does not edit:
+   *   a flow mapping, a key that is not plain text), `alias`, `mismatch` (the result did not read back as asked)
+   */
+  function patch(text, changes) {
+    const source = String(text ?? '');
+    const before = parse(source);
+    if (before.hasFrontmatter && !before.editable) return { ok: false, text: source, reason: before.diagnostics.some((d) => d.severity === 'error') ? 'invalid' : 'unsupported', key: null };
+    let current = source;
+    const entries = Object.entries(changes || {});
+    for (const [key, value] of entries) {
+      const step = patchOne(current, key, value);
+      if (!step.ok) return { ok: false, text: source, reason: step.reason, key };
+      current = step.text;
+    }
+    if (current === source) return { ok: true, text: source, changed: false };
+    // Read back: the keys asked for hold what was asked, every other key what it held, in the same order.
+    const after = parse(current);
+    if (!after.data || after.diagnostics.some((d) => d.severity === 'error')) return { ok: false, text: source, reason: 'mismatch', key: null };
+    const asked = new Map(entries);
+    for (const [key, value] of asked) {
+      const has = Object.prototype.hasOwnProperty.call(after.data, key);
+      if (value === undefined ? has : !(has && deepEqual(after.data[key], plainCopy(value)))) return { ok: false, text: source, reason: 'mismatch', key };
+    }
+    const kept = (before.keys || []).map((k) => k.key).filter((k) => !asked.has(k));
+    const keptAfter = after.keys.map((k) => k.key).filter((k) => !asked.has(k));
+    if (!deepEqual(kept, keptAfter)) return { ok: false, text: source, reason: 'mismatch', key: null };
+    for (const key of kept) {
+      if (!deepEqual(before.data[key], after.data[key])) return { ok: false, text: source, reason: 'mismatch', key };
+    }
+    if (before.body !== after.body) return { ok: false, text: source, reason: 'mismatch', key: null };
+    return { ok: true, text: current, changed: true };
+  }
+
+  return { parse, patch, serializePair, splitFrontmatter, PARSE_OPTIONS };
+}

package/neural-interface/public/shared/skills/ss-ids.js

@@ -0,0 +1,32 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio: artifact ids in a URL
+// ═══════════════════════════════════════════
+//
+// The library's ids (`skill:<folder>`, `command:<file.md>`, `agent:<file.md>`) travel in URLs as the base64url of
+// their UTF-8 bytes; the server decodes them the same way (Buffer.from(id, 'base64url').toString('utf-8')).
+// btoa() alone reads a string as Latin-1: a folder named "café" was sent as other bytes than the server reads,
+// and "技能" threw. Every id is encoded from its UTF-8 bytes here. No DOM: the page and the tests load it.
+
+/** Bytes as base64, in pieces (one String.fromCharCode call on a large array would overflow). */
+function bytesToBase64(bytes) {
+  let bin = '';
+  for (let i = 0; i < bytes.length; i += 0x8000) bin += String.fromCharCode.apply(null, bytes.subarray(i, i + 0x8000));
+  return btoa(bin);
+}
+
+/** An id as the server reads it: base64url (no padding) of its UTF-8 bytes. */
+export function encodeArtifactId(id) {
+  const bytes = new TextEncoder().encode(String(id ?? ''));
+  return bytesToBase64(bytes).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+/** The id an encoded one names ('' when it is not base64url of UTF-8 text). */
+export function decodeArtifactId(encoded) {
+  try {
+    const text = String(encoded ?? '');
+    if (!/^[A-Za-z0-9_-]*$/.test(text)) return '';
+    const padded = text.replace(/-/g, '+').replace(/_/g, '/') + '='.repeat((4 - (text.length % 4)) % 4);
+    const bin = atob(padded);
+    return new TextDecoder('utf-8', { fatal: true }).decode(Uint8Array.from(bin, (c) => c.charCodeAt(0)));
+  } catch { return ''; }
+}

package/neural-interface/public/shared/skills/ss-lint.js

@@ -0,0 +1,149 @@
+// ═══════════════════════════════════════════
+// SynaBun Neural Interface — Skills Studio: what is wrong with a skill, a command or an agent
+// ═══════════════════════════════════════════
+//
+// The checks run on what ss-frontmatter.js parse() read. Each problem names its rule, its severity and its
+// line. An error is a file a runtime will misread (YAML that does not parse, a name that is not text, an
+// agent without a description); a warning is one it will read but that is likely wrong (no description, a
+// name that does not match its folder). Nothing here is decided by truthiness: an empty string, a number or
+// a list where text belongs are each said for what they are.
+//
+// Profile: Claude Code (the folders the Studio edits). The limits that the portable Agent Skills format and
+// Codex enforce too (64-character names, 1024-character descriptions) are errors here as well, so a skill that
+// passes can be carried to the other runtimes. No DOM.
+
+import { findHiddenChars, inspectName } from './ss-unicode.js';
+
+export const LINT_PROFILE = 'claude-code-2026-10';
+export const NAME_MAX = 64;
+export const DESCRIPTION_MAX = 1024;
+const NAME_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+const BOOLEAN_KEYS = ['user-invocable', 'disable-model-invocation'];
+const STRING_KEYS = ['argument-hint', 'model', 'color', 'license', 'compatibility', 'context', 'agent', 'effort', 'when_to_use', 'shell'];
+const TOOL_KEYS = ['allowed-tools', 'disallowed-tools', 'tools'];
+
+const kindOf = (value) => {
+  if (value === undefined) return 'absent';
+  if (value === null) return 'empty';
+  if (Array.isArray(value)) return 'a list';
+  if (typeof value === 'object') return 'a mapping';
+  return typeof value === 'string' ? 'text' : `a ${typeof value}`;
+};
+
+/**
+ * @param {object} o
+ * @param {'skill' | 'command' | 'agent'} o.type
+ * @param {object} o.parsed what ss-frontmatter.js parse() returned
+ * @param {string} [o.folderName] a skill's folder, or a command's / agent's file name without `.md`
+ * @param {string[]} [o.knownNames] names a skill must not pass for (the bundled ones)
+ * @returns {{ profile: string, errors: object[], warnings: object[], infos: object[], all: object[] }}
+ *   each problem `{ ruleId, severity, message, line }`
+ */
+export function lintArtifact({ type, parsed, folderName = '', knownNames = [] }) {
+  const all = [];
+  const add = (ruleId, severity, message, line = null) => all.push({ ruleId, severity, message, line });
+  const lineOf = (key) => parsed?.keys?.find((k) => k.key === key)?.line ?? (parsed?.split?.startLine || 1);
+
+  for (const d of parsed?.diagnostics || []) add(d.ruleId, d.severity, d.message, d.line);
+  const data = parsed?.data;
+  if (!parsed?.hasFrontmatter && !parsed?.split?.unterminated) {
+    if (type === 'agent') add('fm-missing', 'error', 'An agent needs frontmatter with a name and a description.', 1);
+    else if (type === 'skill') add('fm-missing', 'warning', 'No frontmatter: Claude takes the folder name and has no description to decide when to use the skill.', 1);
+  }
+  const has = (key) => !!data && Object.prototype.hasOwnProperty.call(data, key);
+  // Without frontmatter, "fm-missing" says it all: the fields it would hold are not named one by one.
+  const missingSaid = !parsed?.hasFrontmatter;
+
+  if (data) {
+    // name
+    if (has('name')) {
+      const name = data.name;
+      if (typeof name !== 'string') add('name-type', 'error', `"name" must be text; it is ${kindOf(name)}.`, lineOf('name'));
+      else if (!name.trim()) add('name-empty', 'error', '"name" is empty.', lineOf('name'));
+      else {
+        if (name.length > NAME_MAX) add('name-length', 'error', `"name" is ${name.length} characters; the limit is ${NAME_MAX}.`, lineOf('name'));
+        const look = inspectName(name, knownNames);
+        if (look.hidden.length) add('name-hidden-chars', 'error', `"name" holds characters nobody can see: ${look.hidden.map((h) => h.label).join(', ')}.`, lineOf('name'));
+        if (look.confusable) add('name-confusable', 'warning', `"name" mixes in letters of another script that look Latin (reads as "${look.skeleton}").`, lineOf('name'));
+        if (look.impersonates) add('name-impersonates', 'warning', `"name" looks like "${look.impersonates}" but is not it.`, lineOf('name'));
+        // Claude Code, Codex and the portable format ask for this; a name outside it may not be found everywhere.
+        if (type !== 'command' && !look.hidden.length && !NAME_RE.test(name)) add('name-format', 'warning', '"name" should use lowercase letters, digits and single hyphens only (no leading or trailing hyphen).', lineOf('name'));
+        if (type === 'skill' && folderName && name !== folderName) add('name-folder', 'warning', `"name" is "${name}" but the folder is "${folderName}": the skill is invoked by its name.`, lineOf('name'));
+      }
+    } else if (type === 'agent' && !missingSaid) {
+      add('name-missing', 'error', 'An agent needs a "name".', lineOf('name'));
+    }
+
+    // description
+    if (has('description')) {
+      const desc = data.description;
+      if (typeof desc !== 'string') add('description-type', 'error', `"description" must be text; it is ${kindOf(desc)}.`, lineOf('description'));
+      else if (!desc.trim()) add('description-empty', 'error', '"description" is empty.', lineOf('description'));
+      else {
+        // The 1024-character limit is the skill format's (Claude Code, Codex and the portable format refuse a longer
+        // SKILL.md). An agent or a command has none: a long description only costs context, which is no error.
+        if (desc.length > DESCRIPTION_MAX) {
+          if (type === 'skill') add('description-length', 'error', `"description" is ${desc.length} characters; the limit is ${DESCRIPTION_MAX}.`, lineOf('description'));
+          else add('description-length', 'info', `"description" is ${desc.length} characters: every session carries it, so a shorter one leaves more room.`, lineOf('description'));
+        }
+        const hidden = findHiddenChars(desc);
+        if (hidden.length) add('description-hidden-chars', 'error', `"description" holds characters nobody can see: ${hidden.slice(0, 5).map((h) => h.label).join(', ')}${hidden.length > 5 ? '…' : ''}.`, lineOf('description'));
+      }
+    } else if (missingSaid) {
+      // said by fm-missing
+    } else if (type === 'agent') {
+      add('description-missing', 'error', 'An agent needs a "description": it is how Claude decides to use it.', lineOf('description'));
+    } else if (type === 'skill') {
+      add('description-missing', 'warning', 'No "description": Claude cannot tell when to use this skill on its own.', lineOf('description'));
+    } else {
+      add('description-missing', 'info', 'No "description": the command list shows nothing for it.', lineOf('description'));
+    }
+
+    for (const key of BOOLEAN_KEYS) {
+      if (has(key) && typeof data[key] !== 'boolean') add(`${key}-type`, 'error', `"${key}" must be true or false; it is ${kindOf(data[key])}.`, lineOf(key));
+    }
+    for (const key of STRING_KEYS) {
+      // `argument-hint: [message]` is the form Claude Code's own documentation writes: YAML reads the brackets as a
+      // list of text and Claude Code shows it as written. Only another kind of value is an error.
+      if (key === 'argument-hint' && Array.isArray(data[key]) && data[key].every((v) => typeof v === 'string' || typeof v === 'number')) continue;
+      if (has(key) && data[key] !== null && typeof data[key] !== 'string') add(`${key}-type`, 'error', `"${key}" must be text; it is ${kindOf(data[key])}.`, lineOf(key));
+    }
+    for (const key of TOOL_KEYS) {
+      if (!has(key)) continue;
+      const value = data[key];
+      const ok = typeof value === 'string' || (Array.isArray(value) && value.every((t) => typeof t === 'string' && t.trim()));
+      if (!ok) add(`${key}-type`, 'error', `"${key}" must be text or a list of tool names; it is ${kindOf(value)}.`, lineOf(key));
+    }
+    if (has('maxTurns')) {
+      const turns = data.maxTurns;
+      if (!Number.isInteger(turns) || turns < 0) add('maxTurns-type', 'error', '"maxTurns" must be a whole number, 0 or more.', lineOf('maxTurns'));
+    }
+    if (has('hooks') && (data.hooks === null || typeof data.hooks !== 'object' || Array.isArray(data.hooks))) {
+      add('hooks-type', 'error', `"hooks" must be a mapping of events; it is ${kindOf(data.hooks)}.`, lineOf('hooks'));
+    }
+    if (has('metadata') && (data.metadata === null || typeof data.metadata !== 'object' || Array.isArray(data.metadata))) {
+      add('metadata-type', 'error', `"metadata" must be a mapping; it is ${kindOf(data.metadata)}.`, lineOf('metadata'));
+    }
+  }
+
+  const body = String(parsed?.body ?? '');
+  if (!body.trim()) add('body-empty', 'warning', 'The body is empty: there are no instructions.', parsed?.bodyLine || 1);
+  else {
+    const hidden = findHiddenChars(body);
+    if (hidden.length) {
+      const first = hidden[0];
+      add('body-hidden-chars', 'warning', `The instructions hold ${hidden.length === 1 ? 'a character' : `${hidden.length} characters`} nobody can see (${first.label}, line ${first.line + (parsed?.bodyLine || 1) - 1}).`, first.line + (parsed?.bodyLine || 1) - 1);
+    }
+  }
+
+  const rank = { error: 0, warning: 1, info: 2 };
+  all.sort((a, b) => (rank[a.severity] - rank[b.severity]) || ((a.line || 0) - (b.line || 0)));
+  return {
+    profile: LINT_PROFILE,
+    errors: all.filter((d) => d.severity === 'error'),
+    warnings: all.filter((d) => d.severity === 'warning'),
+    infos: all.filter((d) => d.severity === 'info'),
+    all,
+  };
+}