tutuca 0.9.55 → 0.9.57

package/dist/tutuca-cli.js

@@ -3326,14 +3326,18 @@ class ComponentSummary {
 }
 
 class ComponentList {
-  constructor({ items }) {
+  constructor({ items, total = null, truncated = false }) {
     this.items = items;
+    this.total = total ?? items.length;
+    this.truncated = truncated;
   }
 }
 
 class ExampleIndex {
-  constructor({ sections }) {
+  constructor({ sections, total = null, truncated = false }) {
     this.sections = sections;
+    this.total = total ?? sections.reduce((n, s) => n + (s.items?.length ?? 0), 0);
+    this.truncated = truncated;
   }
 }
 
@@ -3815,13 +3819,37 @@ function summarize(comp) {
     fields
   });
 }
-function listComponents(normalized, { name = null } = {}) {
+function listComponents(normalized, { name = null, limit = 0 } = {}) {
   const comps = normalized.components;
   const picked = name === null ? comps : comps.filter((c) => c.name === name);
-  return new ComponentList({ items: picked.map(summarize) });
+  const total = picked.length;
+  const capped = limit > 0 ? picked.slice(0, limit) : picked;
+  return new ComponentList({
+    items: capped.map(summarize),
+    total,
+    truncated: capped.length < total
+  });
 }
-function listExamples(normalized) {
-  return new ExampleIndex({ sections: normalized.sections });
+function listExamples(normalized, { limit = 0 } = {}) {
+  const sections = normalized.sections;
+  const total = sections.reduce((n, s) => n + (s.items?.length ?? 0), 0);
+  if (limit <= 0) {
+    return new ExampleIndex({ sections, total, truncated: false });
+  }
+  const capped = [];
+  let remaining = limit;
+  for (const s of sections) {
+    if (remaining <= 0)
+      break;
+    const items = s.items.slice(0, remaining);
+    capped.push({ ...s, items });
+    remaining -= items.length;
+  }
+  return new ExampleIndex({
+    sections: capped,
+    total,
+    truncated: capped.reduce((n, s) => n + s.items.length, 0) < total
+  });
 }
 var init_list = () => {};
 
@@ -8726,7 +8754,8 @@ var init_transactor = __esm(() => {
     }
     handlerProp = null;
     getHandlerForName(comp) {
-      return comp?.[this.handlerProp]?.[this.name] ?? nullHandler;
+      const handlers = comp?.[this.handlerProp];
+      return handlers?.[this.name] ?? handlers?.$unknown ?? nullHandler;
     }
     getHandlerAndArgs(_root, instance, comps) {
       const handler = this.getHandlerForName(comps.getCompFor(instance));
@@ -8754,6 +8783,9 @@ var init_transactor = __esm(() => {
     }
   };
   EventContext = class EventContext extends Dispatcher {
+    get name() {
+      return this.parent?.name ?? null;
+    }
     stopPropagation() {
       return this.parent.stopPropagation();
     }
@@ -14082,6 +14114,12 @@ var exports__registry = {};
 __export(exports__registry, {
   COMMANDS: () => COMMANDS
 });
+function parseLimit(raw) {
+  if (raw === undefined || raw === null)
+    return 0;
+  const n = Number.parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 0;
+}
 var COMMANDS;
 var init__registry = __esm(() => {
   init_chai();
@@ -14092,7 +14130,7 @@ var init__registry = __esm(() => {
   init_render2();
   init_test();
   COMMANDS = {
-    info: {
+    get: {
       describe: "Summarize the module's exports and counts.",
       defaultFormat: "cli",
       run: (normalized) => describeModule(normalized.mod, { path: normalized.path })
@@ -14100,15 +14138,20 @@ var init__registry = __esm(() => {
     list: {
       describe: "List components in the module.",
       defaultFormat: "cli",
-      run: (normalized) => listComponents(normalized)
+      parseOptions: { limit: { type: "string" } },
+      run: (normalized, { values, positionals }) => listComponents(normalized, {
+        name: positionals[0] ?? null,
+        limit: parseLimit(values.limit)
+      })
     },
     examples: {
       describe: "List examples in the module.",
       defaultFormat: "cli",
-      run: (normalized) => listExamples(normalized)
+      parseOptions: { limit: { type: "string" } },
+      run: (normalized, { values }) => listExamples(normalized, { limit: parseLimit(values.limit) })
     },
-    docs: {
-      describe: "Produce API docs for components (optional <name> for one).",
+    show: {
+      describe: "Show API docs for components (optional <name> for one).",
       defaultFormat: "md",
       run: (normalized, { positionals }) => docComponents(normalized, { name: positionals[0] ?? null })
     },
@@ -14159,160 +14202,807 @@ var init__registry = __esm(() => {
   };
 });
 
-// tools/cli/commands/install-skill.js
-var exports_install_skill = {};
-__export(exports_install_skill, {
-  run: () => run,
-  describe: () => describe
-});
-import { cpSync, existsSync, mkdirSync, readdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, resolve } from "node:path";
-import { fileURLToPath } from "node:url";
-import { parseArgs } from "node:util";
-function findSkillsRoot() {
-  const here = dirname(fileURLToPath(import.meta.url));
-  const candidates = [resolve(here, "..", "..", "..", "skill"), resolve(here, "..", "skill")];
-  for (const c of candidates) {
-    if (existsSync(resolve(c, "tutuca", "SKILL.md")))
-      return c;
+// tools/format/lint.js
+function unsupportedExprMessage(info) {
+  const v = JSON.stringify(info.value);
+  const label = UNSUPPORTED_EXPR_LABEL[info.detected] ?? "expression";
+  switch (info.role) {
+    case "attr":
+      return `Unsupported ${label} ${v} in dynamic attribute ':${info.attr}'`;
+    case "directive":
+      return `Unsupported ${label} ${v} in directive '@${info.directive}'`;
+    case "if":
+      return `Unsupported ${label} ${v} in '@if.${info.attr}' condition`;
+    case "x-op":
+      return `Unsupported ${label} ${v} in <x ${info.op}>`;
+    default:
+      return `Unsupported ${label} ${v}`;
   }
-  return null;
-}
-function targetDir(scope, name, dotAgents) {
-  const base = scope === "user" ? homedir() : process.cwd();
-  const dir = dotAgents ? ".agents/skills" : ".claude/skills";
-  return resolve(base, dir, name);
 }
-function targetHasSkillFiles(dir) {
-  if (!existsSync(dir))
-    return false;
-  for (const entry of readdirSync(dir, { withFileTypes: true })) {
-    if (entry.isFile() && entry.name.endsWith(".md"))
-      return true;
-    if (entry.isDirectory() && targetHasSkillFiles(resolve(dir, entry.name)))
-      return true;
+function badValueMessage(info) {
+  const v = JSON.stringify(info.value);
+  switch (info.role) {
+    case "attr":
+      return `Cannot parse value ${v} for attribute ':${info.attr}'`;
+    case "directive":
+      return `Cannot parse value ${v} for directive '@${info.directive}'`;
+    case "if":
+      return `Cannot parse condition ${v} for '@if.${info.attr}'`;
+    case "x-op":
+      return `Cannot parse value ${v} for <x ${info.op}>`;
+    case "handler-name":
+      return `Cannot parse handler name ${v}`;
+    case "handler-arg":
+      return `Cannot parse handler argument ${v}`;
+    case "macro-var":
+      return `Macro variable '^${info.name}' is not defined`;
+    default:
+      return `Cannot parse value ${v}`;
   }
-  return false;
 }
-function installSkill(skill, root, scope, force, dotAgents) {
-  const src = resolve(root, skill.srcSubdir);
-  if (!existsSync(resolve(src, "SKILL.md"))) {
-    process.stderr.write(`tutuca: missing skill assets for ${skill.name} at ${src}
-`);
-    process.exit(1);
-  }
-  const target = targetDir(scope, skill.name, dotAgents);
-  if (targetHasSkillFiles(target) && !force) {
-    process.stderr.write(`tutuca: ${target} already contains skill files. Re-run with --force to overwrite.
-`);
-    process.exit(1);
-  }
-  mkdirSync(target, { recursive: true });
-  cpSync(src, target, { recursive: true });
-  const baseDir = dotAgents ? ".agents/skills" : ".claude/skills";
-  const rel = scope === "project" ? `${baseDir}/${skill.name}` : target;
-  process.stdout.write(`installed ${skill.name} skill → ${rel}
-`);
+function tagDisplay(tag) {
+  return tag ? String(tag).toLowerCase() : null;
 }
-async function run(argv) {
-  const parsed = parseArgs({
-    args: argv,
-    options: {
-      user: { type: "boolean", default: false },
-      project: { type: "boolean", default: false },
-      "margaui-skill": { type: "boolean", default: false },
-      "immutable-skill": { type: "boolean", default: false },
-      all: { type: "boolean", default: false },
-      "dot-agents": { type: "boolean", default: false },
-      force: { type: "boolean", short: "f", default: false },
-      help: { type: "boolean", short: "h", default: false }
-    },
-    allowPositionals: false
-  });
-  if (parsed.values.help) {
-    process.stdout.write(`tutuca install-skill [--user | --project] [--margaui-skill | --immutable-skill | --all] [--dot-agents] [--force]
-` + `
-` + `  Installs Claude Code skill assets into .claude/skills/<name>/.
-` + `  Defaults to --project (cwd); --user installs at ~/.claude/skills/.
-` + `
-` + `  Selection:
-` + `    (default)         install the tutuca skill
-` + `    --margaui-skill   install the margaui skill instead
-` + `    --immutable-skill install the immutable-js skill instead
-` + `    --all             install every bundled skill (tutuca + margaui + immutable-js)
-` + `
-` + `  --dot-agents installs into .agents/skills/ instead of .claude/skills/.
-` + `  --force overwrites existing files.
-`);
-    return;
-  }
-  if (parsed.values.user && parsed.values.project) {
-    process.stderr.write(`tutuca: --user and --project are mutually exclusive
-`);
-    process.exit(1);
-  }
-  const selectionFlags = ["margaui-skill", "immutable-skill", "all"].filter((k) => parsed.values[k]);
-  if (selectionFlags.length > 1) {
-    process.stderr.write(`tutuca: ${selectionFlags.map((f) => `--${f}`).join(", ")} are mutually exclusive
-`);
-    process.exit(1);
-  }
-  const scope = parsed.values.user ? "user" : "project";
-  const root = findSkillsRoot();
-  if (!root) {
-    process.stderr.write(`tutuca: skill assets not found alongside this CLI.
-` + "If you're running from a checkout, run `bun scripts/build-skill.js` first.\n");
-    process.exit(1);
+function fmtTagSuffix(info) {
+  const t = tagDisplay(info?.tag);
+  return t && t !== "x" ? ` on <${t}>` : "";
+}
+function fmtOriginSuffix(info) {
+  if (!info)
+    return "";
+  const parts = [];
+  if (info.originAttr) {
+    const branch = info.branch ? `[${info.branch}]` : "";
+    parts.push(`in ${info.originAttr}${branch}`);
   }
-  let selected;
-  if (parsed.values.all) {
-    selected = SKILLS;
-  } else {
-    const selFlag = SKILLS.find((s) => s.flag && parsed.values[s.flag]);
-    selected = selFlag ? [selFlag] : SKILLS.filter((s) => s.name === "tutuca");
+  if (info.handlerName) {
+    parts.push(`handler '${info.handlerName}'${info.argIndex !== undefined ? ` arg ${info.argIndex}` : ""}`);
   }
-  for (const skill of selected) {
-    installSkill(skill, root, scope, parsed.values.force, parsed.values["dot-agents"]);
+  const t = tagDisplay(info.tag);
+  if (t && t !== "x")
+    parts.push(`on <${t}>`);
+  return parts.length ? ` (${parts.join(", ")})` : "";
+}
+function fmtEventSuffix(info) {
+  if (info?.originAttr)
+    return ` in ${info.originAttr}`;
+  if (info?.eventName)
+    return ` in @on.${info.eventName}`;
+  return "";
+}
+function lintIdToMessage(id, info) {
+  switch (id) {
+    case "RENDER_IT_OUTSIDE_OF_LOOP":
+      return "<x render-it> used outside of a loop";
+    case "UNKNOWN_EVENT_MODIFIER": {
+      const mods = info.handler?.modifiers ?? [info.modifier];
+      const written = `@on.${info.name}+${mods.join("+")}`;
+      return `Unknown modifier '+${info.modifier}' in '${written}'`;
+    }
+    case "UNKNOWN_HANDLER_ARG_NAME":
+      return `Unknown handler argument '${info.name}'${fmtOriginSuffix(info)}`;
+    case "INPUT_HANDLER_NOT_IMPLEMENTED":
+      return `Input handler '${info.name}' is not implemented${fmtEventSuffix(info)}`;
+    case "INPUT_HANDLER_NOT_REFERENCED":
+      return `Input handler '${info.name}' is defined but never used — remove it or wire it to an @on.* event`;
+    case "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED":
+      return `Method '.${info.name}' is not implemented${fmtEventSuffix(info)}`;
+    case "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD":
+      return `'.${info.name}' is a method reference, but '${info.name}' is defined as an input handler${fmtEventSuffix(info)}`;
+    case "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER":
+      return `'${info.name}' is an input handler reference, but '${info.name}' is defined as a method${fmtEventSuffix(info)}`;
+    case "FIELD_VAL_NOT_DEFINED":
+      return `Field '.${info.name}' is not defined${fmtOriginSuffix(info)}`;
+    case "DUPLICATE_ATTR_DEFINITION": {
+      const sources = info.sources?.length ? ` (${info.sources.join(", ")})` : "";
+      const tag = info.tag ? ` on <${String(info.tag).toLowerCase()}>` : "";
+      return `Attribute '${info.name}' is set ${info.sources?.length ?? "multiple"} times${sources}${tag}`;
+    }
+    case "IF_NO_BRANCH_SET":
+      return `'@if.${info.attr}' has no '@then' or '@else' branch — add '@then="…"' or '@else="…"' (or both)${fmtTagSuffix(info)}`;
+    case "UNKNOWN_REQUEST_NAME":
+      return `Unknown request '!${info.name}'${fmtOriginSuffix(info)}`;
+    case "UNKNOWN_COMPONENT_NAME":
+      return `Unknown component '${info.name}'${fmtOriginSuffix(info)}`;
+    case "ALT_HANDLER_NOT_DEFINED":
+      return `Alter handler '${info.name}' is not defined${fmtOriginSuffix(info)}`;
+    case "ALT_HANDLER_NOT_REFERENCED":
+      return `Alter handler '${info.name}' is defined but never used — remove it or reference it from @when, @enrich-with, or @loop-with`;
+    case "UNKNOWN_MACRO_ARG":
+      return `Argument '${info.name}' is not declared in macro '${info.macroName}'`;
+    case "UNKNOWN_DIRECTIVE":
+      return `Unknown directive '@${info.name}=${JSON.stringify(info.value)}'${fmtTagSuffix(info)}`;
+    case "UNKNOWN_X_OP":
+      return `Unknown <x> op '${info.name}=${JSON.stringify(info.value)}'${fmtTagSuffix(info)}`;
+    case "UNKNOWN_X_ATTR":
+      return `Unknown attribute '${info.name}=${JSON.stringify(info.value)}' on <x ${info.op}>${fmtTagSuffix(info)}`;
+    case "MAYBE_DROP_AT_PREFIX": {
+      const written = info.value !== undefined ? `${info.name}=${JSON.stringify(info.value)}` : info.name;
+      return `'${written}' on <x> looks like a directive but is actually an x op/attr written with a leading '@'`;
+    }
+    case "BAD_VALUE":
+      return `${badValueMessage(info)}${fmtTagSuffix(info)}`;
+    case "UNSUPPORTED_EXPR_SYNTAX":
+      return `${unsupportedExprMessage(info)}${fmtTagSuffix(info)}`;
+    case "REDUNDANT_TEMPLATE_STRING":
+      return `Redundant template string — '{${info.simpler}}' should be just '${info.simpler}'${fmtOriginSuffix(info)}`;
+    case "UNKNOWN_COMPONENT_SPEC_KEY":
+      return `Unknown component spec key '${info.key}' — value will be ignored at runtime`;
+    case "HTML_TAG_NAME_HAS_UPPERCASE":
+      return `Tag <${info.raw}> will be lowercased to <${info.lowercased}>${fmtLocationSuffix(info)}`;
+    case "HTML_SVG_TAG_WILL_LOWERCASE":
+      return `SVG tag <${info.raw}> is not in the WHATWG case-correction list — will be lowercased to <${info.lowercased}>${fmtLocationSuffix(info)}`;
+    case "HTML_TAG_NOT_ALLOWED_IN_PARENT":
+      return `<${info.tag}> not allowed under <${info.parent ?? "?"}> in ${info.mode} — ${htmlActionPhrase(info.action, info.tag, info.parent)}${fmtLocationSuffix(info)}`;
+    case "HTML_TEXT_NOT_ALLOWED_IN_PARENT":
+      return `Non-whitespace text not allowed in ${info.mode}: ${JSON.stringify(info.snippet)}${fmtLocationSuffix(info)}`;
+    case "HTML_VOID_ELEMENT_HAS_CLOSE_TAG":
+      return `Void element <${info.tag}> has an explicit close tag${fmtLocationSuffix(info)}`;
+    case "HTML_DUPLICATE_FORM":
+      return `Nested <form> — the inner form will be dropped by the parser${fmtLocationSuffix(info)}`;
+    case "HTML_NESTED_INTERACTIVE":
+      return `<${info.tag}> nested inside another <${info.tag}> — adoption agency will reorder${fmtLocationSuffix(info)}`;
+    case "HTML_MISNESTED_FORMATTING":
+      return `Misnested formatting tag </${info.tag}> — adoption agency will reorder nodes${fmtLocationSuffix(info)}`;
+    case "HTML_UNEXPECTED_END_TAG":
+      return `Unexpected end tag </${info.tag}>${fmtLocationSuffix(info)}`;
+    case "HTML_UNCLOSED_BEFORE_END":
+      return `<${info.unclosed}> still open when </${info.tag}> was seen — implicitly closed${fmtLocationSuffix(info)}`;
+    case "HTML_DUPLICATE_ATTRIBUTE":
+      return `Duplicate attribute '${info.name}' — second occurrence dropped${fmtLocationSuffix(info)}`;
+    case "HTML_ATTRIBUTES_ON_END_TAG":
+      return `Attributes on end tag </${info.tag}> — dropped by the parser${fmtLocationSuffix(info)}`;
+    case "HTML_SELF_CLOSING_END_TAG":
+      return `Self-closing end tag </${info.tag}/> — trailing '/' is meaningless${fmtLocationSuffix(info)}`;
+    case "HTML_MISSING_ATTRIBUTE_VALUE":
+      return `Attribute '${info.name}' is missing a value${fmtLocationSuffix(info)}`;
+    case "HTML_CDATA_IN_HTML_NAMESPACE":
+      return `CDATA section in HTML namespace — reinterpreted as a bogus comment${fmtLocationSuffix(info)}`;
+    case "HTML_BOGUS_COMMENT":
+      return `Bogus comment — content dropped by the parser${fmtLocationSuffix(info)}`;
+    case "HTML_SVG_ATTR_WILL_LOWERCASE":
+      return `SVG attribute '${info.raw}' will be rewritten to '${info.canonical}'${fmtLocationSuffix(info)}`;
+    case "HTML_MATHML_ATTR_WILL_LOWERCASE":
+      return `MathML attribute '${info.raw}' will be rewritten to '${info.canonical}'${fmtLocationSuffix(info)}`;
+    case "LINT_ERROR":
+      return info.message;
+    default:
+      return id;
   }
-  process.stdout.write(`Open a Claude Code session in this directory to use it.
-`);
 }
-var describe = "Install Claude Code skills (tutuca, margaui, immutable-js) into .claude/skills/.", SKILLS;
-var init_install_skill = __esm(() => {
-  SKILLS = [
+function suggestionToMessage(suggestion) {
+  if (!suggestion)
+    return null;
+  switch (suggestion.kind) {
+    case "replace-name":
+      return `did you mean '${suggestion.to}'?`;
+    case "drop-prefix":
+      return `did you mean '${suggestion.to}'? (drop the leading '${suggestion.from.slice(0, suggestion.from.length - suggestion.to.length)}')`;
+    case "add-prefix":
+      return `did you mean '${suggestion.to}'? (add the leading '${suggestion.to.slice(0, suggestion.to.length - suggestion.from.length)}')`;
+    case "remove":
+      return `remove ${suggestion.what}`;
+    case "rewrite":
+      return `use '${suggestion.to}' instead of '${suggestion.from}'`;
+    case "wrap":
+      return `wrap it in ${suggestion.to}`;
+    case "rephrase":
+      return suggestion.text ?? null;
+    default:
+      return null;
+  }
+}
+function fmtLocationSuffix(info) {
+  const loc = info?.location;
+  if (!loc)
+    return "";
+  return ` at line ${loc.line}, col ${loc.column}`;
+}
+function htmlActionPhrase(action, tag, parent) {
+  switch (action) {
+    case "ignored":
+      return `the parser will drop this <${tag}>`;
+    case "drop":
+      return `the parser will drop this <${tag}>`;
+    case "auto-close-implicit":
+      return `the parser will close <${parent ?? "?"}> first, then place <${tag}> as a sibling`;
+    case "foster-parent":
+      return `the parser will move <${tag}> outside <${parent ?? "?"}> (foster-parenting)`;
+    case "foreign-breakout":
+      return `the parser will exit foreign content and re-process <${tag}> in HTML mode`;
+    default:
+      return `parser action: ${action}`;
+  }
+}
+var UNSUPPORTED_EXPR_LABEL;
+var init_lint2 = __esm(() => {
+  UNSUPPORTED_EXPR_LABEL = {
+    ternary: "ternary expression",
+    comparison: "comparison",
+    logical: "logical expression",
+    "call-with-args": "method call with arguments"
+  };
+});
+
+// tools/cli/errors.js
+var exports_errors = {};
+__export(exports_errors, {
+  parseArgsErrorShape: () => parseArgsErrorShape,
+  emitError: () => emitError,
+  didYouMean: () => didYouMean,
+  CODES: () => CODES
+});
+function isJsonFormat(opts) {
+  return opts?.format === "json";
+}
+function emitError(opts, shape) {
+  const exit = shape.exit ?? 1;
+  if (isJsonFormat(opts)) {
+    const envelope = {
+      error: {
+        code: shape.code ?? CODES.INTERNAL,
+        message: shape.message
+      }
+    };
+    if (shape.suggestion)
+      envelope.error.suggestion = shape.suggestion;
+    if (shape.hint)
+      envelope.error.hint = shape.hint;
+    if (shape.where)
+      envelope.error.where = shape.where;
+    process.stderr.write(`${JSON.stringify(envelope)}
+`);
+  } else {
+    const where = shape.where ? `[${shape.where}] ` : "";
+    process.stderr.write(`tutuca: ${where}${shape.message}
+`);
+    const tail = suggestionToMessage(shape.suggestion);
+    if (tail)
+      process.stderr.write(`  ${tail}
+`);
+    if (shape.hint)
+      process.stderr.write(`  hint: ${shape.hint}
+`);
+  }
+  process.exit(exit);
+}
+function didYouMean(name, candidates) {
+  const close = closestName(name, candidates);
+  return close ? { kind: "replace-name", from: name, to: close } : null;
+}
+function parseArgsErrorShape(err, validFlags) {
+  if (!err?.code?.startsWith?.("ERR_PARSE_ARGS_"))
+    return null;
+  if (err.code === "ERR_PARSE_ARGS_UNKNOWN_OPTION") {
+    const m = err.message.match(/Unknown option '(-{1,2}[^']+)'/);
+    const raw = m?.[1] ?? null;
+    const stripped = raw?.replace(/^-+/, "");
+    const candidates = [...validFlags ?? []];
+    const close = stripped ? closestName(stripped, candidates) : null;
+    return {
+      code: CODES.USAGE_UNKNOWN_FLAG,
+      message: raw ? `Unknown flag '${raw}'` : err.message,
+      suggestion: close ? { kind: "replace-name", from: raw, to: `--${close}` } : null,
+      hint: candidates.length ? `Valid flags: ${candidates.map((f) => `--${f}`).join(", ")}` : null
+    };
+  }
+  if (err.code === "ERR_PARSE_ARGS_INVALID_OPTION_VALUE") {
+    return { code: CODES.USAGE_BAD_FLAG_VALUE, message: err.message };
+  }
+  return { code: err.code, message: err.message };
+}
+var CODES;
+var init_errors = __esm(() => {
+  init_lint2();
+  CODES = {
+    USAGE_UNKNOWN_COMMAND: "ERR_USAGE_UNKNOWN_COMMAND",
+    USAGE_UNKNOWN_FLAG: "ERR_USAGE_UNKNOWN_FLAG",
+    USAGE_BAD_FLAG_VALUE: "ERR_USAGE_BAD_FLAG_VALUE",
+    USAGE_MISSING_MODULE: "ERR_USAGE_MISSING_MODULE",
+    USAGE_MUTUALLY_EXCLUSIVE: "ERR_USAGE_MUTUALLY_EXCLUSIVE",
+    USAGE_MISSING_ARGUMENT: "ERR_USAGE_MISSING_ARGUMENT",
+    FORMAT_UNKNOWN: "ERR_FORMAT_UNKNOWN",
+    FORMAT_UNSUPPORTED: "ERR_FORMAT_UNSUPPORTED",
+    MODULE_LOAD_FAILED: "ERR_MODULE_LOAD_FAILED",
+    MODULE_SHAPE_MISMATCH: "EXAMPLES_SHAPE_MISMATCH",
+    SKILL_ASSETS_MISSING: "ERR_SKILL_ASSETS_MISSING",
+    SKILL_TARGET_EXISTS: "ERR_SKILL_TARGET_EXISTS",
+    INTERNAL: "ERR_INTERNAL"
+  };
+});
+
+// tools/cli/commands/feedback.js
+var exports_feedback = {};
+__export(exports_feedback, {
+  run: () => run2,
+  describe: () => describe2
+});
+import { appendFileSync, existsSync as existsSync2, mkdirSync, readFileSync as readFileSync2 } from "node:fs";
+import { homedir } from "node:os";
+import { dirname as dirname2, resolve as resolve2 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import { parseArgs } from "node:util";
+function readPackageVersion() {
+  const here = dirname2(fileURLToPath2(import.meta.url));
+  const candidates = [
+    resolve2(here, "..", "..", "..", "package.json"),
+    resolve2(here, "..", "package.json")
+  ];
+  for (const p of candidates) {
+    if (existsSync2(p)) {
+      try {
+        return JSON.parse(readFileSync2(p, "utf8")).version ?? null;
+      } catch {}
+    }
+  }
+  return null;
+}
+function readStdinSync() {
+  if (process.stdin.isTTY)
+    return "";
+  try {
+    return readFileSync2(0, "utf8");
+  } catch {
+    return "";
+  }
+}
+async function run2(argv, opts = {}) {
+  const parsed = parseArgs({
+    args: argv,
+    options: { help: { type: "boolean", short: "h", default: false } },
+    allowPositionals: true
+  });
+  if (parsed.values.help) {
+    process.stdout.write(HELP);
+    return;
+  }
+  const positional = parsed.positionals.join(" ").trim();
+  const message = positional || readStdinSync().trim();
+  if (!message) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_ARGUMENT,
+      message: "feedback requires a message (positional arg or piped stdin)",
+      hint: 'Example: `tutuca feedback "the lint code FIELD_VAL_NOT_DEFINED was confusing"` ' + "or `echo ... | tutuca feedback`."
+    });
+  }
+  const record = {
+    ts: new Date().toISOString(),
+    version: readPackageVersion(),
+    message
+  };
+  const dir = resolve2(homedir(), ".tutuca");
+  const file = resolve2(dir, "feedback.jsonl");
+  mkdirSync(dir, { recursive: true });
+  appendFileSync(file, `${JSON.stringify(record)}
+`);
+  process.stdout.write(`recorded feedback → ${file}
+`);
+}
+var describe2 = "Record freeform feedback (bug, confusion, suggestion) to ~/.tutuca/feedback.jsonl.", HELP;
+var init_feedback = __esm(() => {
+  init_errors();
+  HELP = `tutuca feedback [message]
+` + `
+` + `  Append a feedback record to ~/.tutuca/feedback.jsonl (created if missing).
+` + `  Use this for bugs, confusing messages, or suggestions about the CLI,
+` + `  bundled skills, docs, or the library itself.
+` + `
+` + `  Provide the message as a positional argument:
+` + `    tutuca feedback "the lint code FIELD_VAL_NOT_DEFINED was confusing"
+` + `
+` + `  ...or via stdin (useful for multi-line notes):
+` + `    echo "..." | tutuca feedback
+` + `    tutuca feedback < notes.txt
+` + `
+` + `  Each record is one JSON object per line: {ts, version, message}.
+`;
+});
+
+// tools/cli/commands/install-skill.js
+var exports_install_skill = {};
+__export(exports_install_skill, {
+  run: () => run3,
+  describe: () => describe3
+});
+import { cpSync, existsSync as existsSync3, mkdirSync as mkdirSync2, readdirSync } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { dirname as dirname3, relative, resolve as resolve3 } from "node:path";
+import { fileURLToPath as fileURLToPath3 } from "node:url";
+import { parseArgs as parseArgs2 } from "node:util";
+function findSkillsRoot() {
+  const here = dirname3(fileURLToPath3(import.meta.url));
+  const candidates = [resolve3(here, "..", "..", "..", "skill"), resolve3(here, "..", "skill")];
+  for (const c of candidates) {
+    if (existsSync3(resolve3(c, "tutuca", "SKILL.md")))
+      return c;
+  }
+  return null;
+}
+function targetDir(scope, name, dotAgents) {
+  const base = scope === "user" ? homedir2() : process.cwd();
+  const dir = dotAgents ? ".agents/skills" : ".claude/skills";
+  return resolve3(base, dir, name);
+}
+function targetHasSkillFiles(dir) {
+  if (!existsSync3(dir))
+    return false;
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isFile() && entry.name.endsWith(".md"))
+      return true;
+    if (entry.isDirectory() && targetHasSkillFiles(resolve3(dir, entry.name)))
+      return true;
+  }
+  return false;
+}
+function listFiles(srcRoot, srcDir, acc) {
+  for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+    const full = resolve3(srcDir, entry.name);
+    if (entry.isDirectory())
+      listFiles(srcRoot, full, acc);
+    else if (entry.isFile())
+      acc.push(relative(srcRoot, full));
+  }
+  return acc;
+}
+function installSkill(skill, root, scope, force, dotAgents, dryRun, opts) {
+  const src = resolve3(root, skill.srcSubdir);
+  if (!existsSync3(resolve3(src, "SKILL.md"))) {
+    emitError(opts, {
+      code: CODES.SKILL_ASSETS_MISSING,
+      message: `missing skill assets for '${skill.name}' at ${src}`,
+      hint: "If you're running from a checkout, run `bun scripts/build-skill.js` first."
+    });
+  }
+  const target = targetDir(scope, skill.name, dotAgents);
+  if (targetHasSkillFiles(target) && !force) {
+    emitError(opts, {
+      code: CODES.SKILL_TARGET_EXISTS,
+      message: `${target} already contains skill files`,
+      hint: "Re-run with --force to overwrite, or --dry-run to see what would change."
+    });
+  }
+  const baseDir = dotAgents ? ".agents/skills" : ".claude/skills";
+  const rel = scope === "project" ? `${baseDir}/${skill.name}` : target;
+  if (dryRun) {
+    const files = listFiles(src, src, []);
+    process.stdout.write(`would install ${skill.name} skill → ${rel}
+`);
+    for (const f of files)
+      process.stdout.write(`  + ${f}
+`);
+    return;
+  }
+  mkdirSync2(target, { recursive: true });
+  cpSync(src, target, { recursive: true });
+  process.stdout.write(`installed ${skill.name} skill → ${rel}
+`);
+}
+async function run3(argv, opts = {}) {
+  const parsed = parseArgs2({
+    args: argv,
+    options: {
+      user: { type: "boolean", default: false },
+      project: { type: "boolean", default: false },
+      "margaui-skill": { type: "boolean", default: false },
+      "immutable-skill": { type: "boolean", default: false },
+      all: { type: "boolean", default: false },
+      "dot-agents": { type: "boolean", default: false },
+      "dry-run": { type: "boolean", default: false },
+      force: { type: "boolean", short: "f", default: false },
+      help: { type: "boolean", short: "h", default: false }
+    },
+    allowPositionals: false
+  });
+  if (parsed.values.help) {
+    process.stdout.write(`tutuca install-skill [--user | --project] [--margaui-skill | --immutable-skill | --all]
+` + `                    [--dot-agents] [--dry-run] [--force]
+` + `
+` + `  Installs Claude Code skill assets into .claude/skills/<name>/.
+` + `  Defaults to --project (cwd); --user installs at ~/.claude/skills/.
+` + `
+` + `  Selection:
+` + `    (default)         install the tutuca skill
+` + `    --margaui-skill   install the margaui skill instead
+` + `    --immutable-skill install the immutable-js skill instead
+` + `    --all             install every bundled skill (tutuca + margaui + immutable-js)
+` + `
+` + `  --dot-agents installs into .agents/skills/ instead of .claude/skills/.
+` + `  --dry-run prints the files that would be written without touching the filesystem.
+` + `  --force overwrites existing files.
+`);
+    return;
+  }
+  if (parsed.values.user && parsed.values.project) {
+    emitError(opts, {
+      code: CODES.USAGE_MUTUALLY_EXCLUSIVE,
+      message: "--user and --project are mutually exclusive",
+      hint: "Use --user for ~/.claude/skills/ or --project (the default) for ./.claude/skills/."
+    });
+  }
+  const selectionFlags = ["margaui-skill", "immutable-skill", "all"].filter((k) => parsed.values[k]);
+  if (selectionFlags.length > 1) {
+    emitError(opts, {
+      code: CODES.USAGE_MUTUALLY_EXCLUSIVE,
+      message: `${selectionFlags.map((f) => `--${f}`).join(", ")} are mutually exclusive`,
+      hint: "Pick one skill, or use --all to install every bundled skill."
+    });
+  }
+  const scope = parsed.values.user ? "user" : "project";
+  const root = findSkillsRoot();
+  if (!root) {
+    emitError(opts, {
+      code: CODES.SKILL_ASSETS_MISSING,
+      message: "skill assets not found alongside this CLI",
+      hint: "If you're running from a checkout, run `bun scripts/build-skill.js` first."
+    });
+  }
+  let selected;
+  if (parsed.values.all) {
+    selected = SKILLS;
+  } else {
+    const selFlag = SKILLS.find((s) => s.flag && parsed.values[s.flag]);
+    selected = selFlag ? [selFlag] : SKILLS.filter((s) => s.name === "tutuca");
+  }
+  for (const skill of selected) {
+    installSkill(skill, root, scope, parsed.values.force, parsed.values["dot-agents"], parsed.values["dry-run"], opts);
+  }
+  if (!parsed.values["dry-run"]) {
+    process.stdout.write(`Open a Claude Code session in this directory to use it.
+`);
+  }
+}
+var describe3 = "Install Claude Code skills (tutuca, margaui, immutable-js) into .claude/skills/.", SKILLS;
+var init_install_skill = __esm(() => {
+  init_errors();
+  SKILLS = [
     { name: "tutuca", srcSubdir: "tutuca", flag: null },
     { name: "margaui", srcSubdir: "margaui", flag: "margaui-skill" },
     { name: "immutable-js", srcSubdir: "immutable-js", flag: "immutable-skill" }
   ];
 });
 
+// tools/cli/commands/agent-context.js
+init__registry();
+var exports_agent_context = {};
+__export(exports_agent_context, {
+  run: () => run,
+  describe: () => describe
+});
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+var describe = "Print a machine-readable schema (commands, flags, exit codes) as JSON.";
+var SCHEMA_VERSION = 1;
+var GLOBAL_FLAGS = [
+  {
+    name: "json",
+    type: "boolean",
+    description: "Shorthand for --format=json. Errors also emit JSON on stderr."
+  },
+  {
+    name: "format",
+    short: "f",
+    type: "string",
+    enum: ["cli", "md", "json", "html"],
+    description: "Output format. Per-command default below; html is render-only; json works for every module command."
+  },
+  {
+    name: "output",
+    short: "o",
+    type: "string",
+    description: "Write to file instead of stdout."
+  },
+  { name: "pretty", type: "boolean", description: "Pretty-print HTML/JSON output." },
+  {
+    name: "module",
+    type: "string",
+    description: "Alternative to first-positional module path."
+  },
+  { name: "help", short: "h", type: "boolean", description: "Show help." }
+];
+var EXIT_CODES = [
+  { code: 0, meaning: "success" },
+  { code: 1, meaning: "usage error (bad args, missing module, bad module shape)" },
+  { code: 2, meaning: "lint findings at error level (lint command)" },
+  { code: 3, meaning: "render crash (render command)" },
+  { code: 4, meaning: "test failures (test command)" }
+];
+var ERROR_CODES = [
+  "ERR_USAGE_UNKNOWN_COMMAND",
+  "ERR_USAGE_UNKNOWN_FLAG",
+  "ERR_USAGE_BAD_FLAG_VALUE",
+  "ERR_USAGE_MISSING_MODULE",
+  "ERR_USAGE_MISSING_ARGUMENT",
+  "ERR_USAGE_MUTUALLY_EXCLUSIVE",
+  "ERR_FORMAT_UNKNOWN",
+  "ERR_FORMAT_UNSUPPORTED",
+  "EXAMPLES_SHAPE_MISMATCH",
+  "ERR_SKILL_ASSETS_MISSING",
+  "ERR_SKILL_TARGET_EXISTS"
+];
+var COMMAND_FLAGS = {
+  list: [
+    {
+      name: "limit",
+      type: "string",
+      description: "Cap number of components emitted (0 = all). Truncated output is signaled by `truncated: true` in JSON."
+    }
+  ],
+  examples: [
+    {
+      name: "limit",
+      type: "string",
+      description: "Cap total number of example items emitted (0 = all)."
+    }
+  ],
+  render: [
+    { name: "title", type: "string", description: "Filter by example title." },
+    { name: "view", type: "string", description: "Override example's view name." }
+  ],
+  test: [
+    {
+      name: "grep",
+      type: "string",
+      description: "Substring match against the full test path."
+    },
+    {
+      name: "bail",
+      type: "boolean",
+      description: "Stop on first failure; remaining tests reported as skip."
+    }
+  ]
+};
+var NO_MODULE_COMMANDS_META = {
+  help: {
+    describe: "Show usage. `help <command>` for per-command detail.",
+    needsModule: false,
+    flags: [{ name: "help", short: "h", type: "boolean" }],
+    positionals: [{ name: "command", required: false }]
+  },
+  feedback: {
+    describe: "Append a feedback record to ~/.tutuca/feedback.jsonl.",
+    needsModule: false,
+    flags: [{ name: "help", short: "h", type: "boolean" }],
+    positionals: [
+      {
+        name: "message",
+        required: false,
+        note: "Falls back to piped stdin when omitted."
+      }
+    ]
+  },
+  "install-skill": {
+    describe: "Copy bundled Claude Code skill assets into .claude/skills/<name>/.",
+    needsModule: false,
+    flags: [
+      { name: "user", type: "boolean", description: "Install at ~/.claude/skills/." },
+      {
+        name: "project",
+        type: "boolean",
+        description: "Install at ./.claude/skills/ (default)."
+      },
+      { name: "margaui-skill", type: "boolean" },
+      { name: "immutable-skill", type: "boolean" },
+      { name: "all", type: "boolean", description: "Install every bundled skill." },
+      {
+        name: "dot-agents",
+        type: "boolean",
+        description: "Use .agents/skills/ instead of .claude/skills/."
+      },
+      {
+        name: "dry-run",
+        type: "boolean",
+        description: "Print files that would be written; don't touch disk."
+      },
+      {
+        name: "force",
+        short: "f",
+        type: "boolean",
+        description: "Overwrite existing files."
+      },
+      { name: "help", short: "h", type: "boolean" }
+    ],
+    positionals: []
+  },
+  "agent-context": {
+    describe: "Print this schema as JSON.",
+    needsModule: false,
+    flags: [],
+    positionals: []
+  }
+};
+function packageVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    resolve(here, "..", "..", "..", "package.json"),
+    resolve(here, "..", "..", "package.json")
+  ];
+  for (const p of candidates) {
+    if (existsSync(p)) {
+      try {
+        return JSON.parse(readFileSync(p, "utf8")).version ?? null;
+      } catch {}
+    }
+  }
+  return null;
+}
+function moduleCommandSchema(name, cmd) {
+  return {
+    name,
+    describe: cmd.describe,
+    needsModule: true,
+    needsEnv: !!cmd.needsEnv,
+    defaultFormat: cmd.defaultFormat,
+    flags: COMMAND_FLAGS[name] ?? [],
+    positionals: [
+      {
+        name: "module-path",
+        required: true,
+        description: "Path to the ES module to inspect."
+      },
+      {
+        name: "name",
+        required: false,
+        description: "Component name filter (operate on one component)."
+      }
+    ]
+  };
+}
+async function run() {
+  const moduleCmds = Object.entries(COMMANDS).map(([name, cmd]) => moduleCommandSchema(name, cmd));
+  const noModuleCmds = Object.entries(NO_MODULE_COMMANDS_META).map(([name, meta]) => ({
+    name,
+    ...meta
+  }));
+  const schema = {
+    schemaVersion: SCHEMA_VERSION,
+    cli: "tutuca",
+    version: packageVersion(),
+    invocation: {
+      synopsis: "tutuca <command> <module-path> [name] [flags]",
+      moduleFirst: false,
+      moduleFlag: "module",
+      note: "For module-required commands, the module path is the second positional. Use --module=<path> as an alternative."
+    },
+    globalFlags: GLOBAL_FLAGS,
+    formats: ["cli", "md", "json", "html"],
+    exitCodes: EXIT_CODES,
+    errorCodes: ERROR_CODES,
+    commands: [...moduleCmds, ...noModuleCmds]
+  };
+  process.stdout.write(`${JSON.stringify(schema, null, 2)}
+`);
+}
+
 // tools/tutuca.js
 init__registry();
+init_feedback();
 
 // tools/cli/commands/help.js
 var exports_help = {};
 __export(exports_help, {
-  run: () => run2,
-  describe: () => describe2
+  run: () => run4,
+  describe: () => describe4
 });
-var describe2 = "Show usage. `help <command>` for per-command detail.";
+var describe4 = "Show usage. `help <command>` for per-command detail.";
 var OVERVIEW = `tutuca — CLI for inspecting, documenting, linting and rendering tutuca
 components defined in an ES module.
 
 SYNOPSIS
-  tutuca <module-path> <command> [name] [flags]
+  tutuca <command> <module-path> [name] [flags]
   tutuca help [command]
   tutuca {-h | --help}
 
 INVOCATION SHAPE
-  - <module-path> comes FIRST (before the command). It is a path to an ES
-    module resolvable by Node (absolute, or relative to cwd).
+  - <command> comes FIRST. <module-path> is the second positional — a path
+    to an ES module resolvable by Node (absolute, or relative to cwd).
+    Use --module=<path> as an alternative if the path conflicts.
   - [name] is an OPTIONAL component-name filter. Omit it to operate on all
-    components; pass it to operate on exactly one (e.g. \`docs Button\`).
-  - Flags may appear anywhere. Global flags and command flags share the
-    same argv; unknown flags are rejected by the subcommand's parser.
-  - \`help\` does NOT take a module path.
+    components; pass it to operate on exactly one (e.g. \`show Button\`).
+  - Per-command flags follow the module path; global flags can appear
+    anywhere. Unknown flags are rejected by the subcommand's parser.
+  - \`help\`, \`feedback\`, \`install-skill\`, \`agent-context\` do NOT take a
+    module path.
 
 MODULE CONVENTION
   A module passed to tutuca must export one or more of:
@@ -14346,27 +15036,31 @@ MODULE CONVENTION
     export function getRoot()             // optional; returned by info
 
 COMMANDS (require <module-path>)
-  info
+  get <module>
       Summarize which getX() exports are present and count components,
       macros, request handlers, examples, and sections. Good first step.
 
-  list
+  list <module> [name] [--limit <n>]
       List each component with its declared views and fields (name, type).
+      --limit caps the number of components emitted (0 = all). Truncated
+      output ends with a "… N more" footer in cli/md, or \`truncated:true\`
+      in JSON.
 
-  examples
+  examples <module> [--limit <n>]
       Print the module's example sections: title, description, items.
       Each item shows its resolved component name and view.
+      --limit caps the total number of items emitted (0 = all).
 
-  docs [name]
-      Generate API docs (methods, input handlers, fields with their
+  show <module> [name]
+      Show API docs (methods, input handlers, fields with their
       auto-generated accessor/mutator methods) for every component, or
       for the single component whose name matches [name].
 
-  lint [name]
+  lint <module> [name]
       Run the built-in component linter. Reports at levels error / warn
       / hint. Exits 2 if ANY finding is at error level.
 
-  render [name] [--title <t>] [--view <v>]
+  render <module> [name] [--title <t>] [--view <v>]
       Render examples to HTML by running each example value through the
       component tree in a headless DOM. Filters:
         [name]       only examples whose value is an instance of <name>
@@ -14374,7 +15068,7 @@ COMMANDS (require <module-path>)
         --view <v>   override the example's view name
       Exits 3 if any render crashes.
 
-  test [name] [--grep <pattern>] [--bail]
+  test <module> [name] [--grep <pattern>] [--bail]
       Run tests defined by getTests({ describe, test, expect }). Filters:
         [name]       only tests whose tagged componentName equals <name>
         --grep <p>   substring match against the full test path
@@ -14387,7 +15081,18 @@ COMMANDS (no module required)
       Without [command]: prints this full reference.
       With [command]: prints that command's one-line description.
 
-  install-skill [--user | --project] [--margaui-skill | --immutable-skill | --all] [--dot-agents] [--force]
+  feedback [message]
+      Append a feedback record (one JSON object per line) to
+      ~/.tutuca/feedback.jsonl. Use for bugs, confusing messages,
+      or suggestions about the CLI, skills, docs, or the library.
+      Message comes from the positional arg or piped stdin.
+
+  agent-context
+      Print a machine-readable schema of every command, flag, exit code,
+      and error code as JSON on stdout. Use this once to teach an agent the
+      shape of the CLI; the schema is versioned (schemaVersion field).
+
+  install-skill [--user | --project] [--margaui-skill | --immutable-skill | --all] [--dot-agents] [--dry-run] [--force]
       Copy bundled Claude Code skill assets into .claude/skills/<name>/.
       Scope: --project (cwd, default) or --user (~/.claude/skills/).
       Selection (default is the tutuca skill):
@@ -14395,9 +15100,13 @@ COMMANDS (no module required)
         --immutable-skill  install the immutable-js skill instead
         --all              install every bundled skill
       --dot-agents installs into .agents/skills/ instead of .claude/skills/.
+      --dry-run prints the files that would be written without touching disk.
       --force overwrites existing files.
 
 GLOBAL FLAGS
+      --json                 Shorthand for \`--format=json\`. Recommended for
+                             agent/script consumers — error envelopes are
+                             also emitted as JSON on stderr.
   -f, --format <cli|md|json|html>
       Output format. Defaults per command:
         info, list, examples, lint -> cli
@@ -14419,44 +15128,56 @@ EXIT CODES
   3   render crash
   4   test failures
 
+ERROR FORMAT
+  Diagnostics go to stderr; structured output goes to stdout. Under
+  \`--json\`, errors are emitted as a single-line JSON envelope on stderr:
+    {"error":{"code":"ERR_...","message":"...","suggestion":{...},"hint":"..."}}
+  Errors include "did you mean" suggestions for unknown commands and flags
+  in the same shape as lint suggestions.
+
 EXAMPLES
   # Inspect a module
-  tutuca ./src/components.js info
+  tutuca get ./src/components.js
 
   # Machine-readable docs for one component
-  tutuca ./src/components.js docs Button -f json -o docs/button.json
+  tutuca show ./src/components.js Button --json -o docs/button.json
 
   # Render every example, pretty-printed HTML to a file
-  tutuca ./src/components.js render -f html --pretty -o out/examples.html
+  tutuca render ./src/components.js -f html --pretty -o out/examples.html
 
   # Render a single example
-  tutuca ./src/components.js render Button --title "Disabled state"
+  tutuca render ./src/components.js Button --title "Disabled state"
 
   # Post-edit verification: lint, then render the example you changed
-  tutuca ./src/components.js lint
-  tutuca ./src/components.js render --title "Disabled state"
+  tutuca lint ./src/components.js
+  tutuca render ./src/components.js --title "Disabled state"
 `;
-async function run2(argv) {
+async function run4(argv, opts = {}) {
   const target = argv?.[0];
   if (!target) {
     process.stdout.write(OVERVIEW);
     return;
   }
   if (target === "help") {
-    process.stdout.write(`help: ${describe2}
+    process.stdout.write(`help: ${describe4}
 `);
     return;
   }
   const { COMMANDS: COMMANDS2 } = await Promise.resolve().then(() => (init__registry(), exports__registry));
   const noModule = {
+    feedback: await Promise.resolve().then(() => (init_feedback(), exports_feedback)),
     "install-skill": await Promise.resolve().then(() => (init_install_skill(), exports_install_skill))
   };
   const cmd = COMMANDS2[target] ?? noModule[target];
   if (!cmd) {
-    process.stderr.write(`tutuca: unknown command: ${target}
-`);
-    process.stderr.write("Run `tutuca help` for the full reference.\n");
-    process.exit(1);
+    const { CODES: CODES2, didYouMean: didYouMean2, emitError: emitError2 } = await Promise.resolve().then(() => (init_errors(), exports_errors));
+    const known = [...Object.keys(COMMANDS2), ...Object.keys(noModule), "help"];
+    emitError2(opts, {
+      code: CODES2.USAGE_UNKNOWN_COMMAND,
+      message: `Unknown command '${target}'`,
+      suggestion: didYouMean2(target, known),
+      hint: "Run `tutuca help` for the full reference."
+    });
   }
   process.stdout.write(`${target}: ${cmd.describe}
 `);
@@ -14465,299 +15186,82 @@ async function run2(argv) {
 
 // tools/tutuca.js
 init_install_skill();
+init_errors();
 
 // tools/cli/with-module.js
-import { parseArgs as parseArgs2 } from "node:util";
-
-// tools/cli/env.js
-init_anode();
-init_lint_check();
-import { JSDOM, VirtualConsole } from "jsdom";
-async function createNodeEnv() {
-  const virtualConsole = new VirtualConsole;
-  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
-  virtualConsole.on("jsdomError", (err) => {
-    if (err?.message?.includes("Could not parse CSS stylesheet"))
-      return;
-    console.error(err.message);
-  });
-  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
-    virtualConsole
-  });
-  const { document: document2, Text, Comment } = dom.window;
-  globalThis.document = document2;
-
-  class HeadlessParseContext extends ParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-
-  class HeadlessLintParseContext extends LintParseContext {
-    constructor() {
-      super(document2, Text, Comment);
-    }
-  }
-  return {
-    document: dom.window.document,
-    ParseContext: HeadlessParseContext,
-    LintParseContext: HeadlessLintParseContext
-  };
-}
-
-// tools/cli/load.js
-import { resolve as resolve2 } from "node:path";
-async function loadAndNormalize(modulePath) {
-  const abs = resolve2(modulePath);
-  const mod = await import(abs);
-  const { normalized } = normalizeModule(mod, { path: abs });
-  return normalized;
-}
-
-// tools/cli/output.js
-import { writeFileSync } from "node:fs";
-
-// tools/format/cli.js
-var exports_cli = {};
-__export(exports_cli, {
-  supports: () => supports,
-  format: () => format
-});
-
-// tools/format/_dispatch.js
-function makeFormatter(name, table) {
-  return {
-    supports: new Set(Object.keys(table)),
-    async format(result, opts) {
-      const fn = table[result.constructor.name];
-      if (!fn) {
-        throw new Error(`${name} formatter missing dispatch for ${result.constructor.name}`);
-      }
-      return await fn(result, opts);
-    }
-  };
-}
-
-// tools/format/lint.js
-var UNSUPPORTED_EXPR_LABEL = {
-  ternary: "ternary expression",
-  comparison: "comparison",
-  logical: "logical expression",
-  "call-with-args": "method call with arguments"
-};
-function unsupportedExprMessage(info) {
-  const v = JSON.stringify(info.value);
-  const label = UNSUPPORTED_EXPR_LABEL[info.detected] ?? "expression";
-  switch (info.role) {
-    case "attr":
-      return `Unsupported ${label} ${v} in dynamic attribute ':${info.attr}'`;
-    case "directive":
-      return `Unsupported ${label} ${v} in directive '@${info.directive}'`;
-    case "if":
-      return `Unsupported ${label} ${v} in '@if.${info.attr}' condition`;
-    case "x-op":
-      return `Unsupported ${label} ${v} in <x ${info.op}>`;
-    default:
-      return `Unsupported ${label} ${v}`;
-  }
-}
-function badValueMessage(info) {
-  const v = JSON.stringify(info.value);
-  switch (info.role) {
-    case "attr":
-      return `Cannot parse value ${v} for attribute ':${info.attr}'`;
-    case "directive":
-      return `Cannot parse value ${v} for directive '@${info.directive}'`;
-    case "if":
-      return `Cannot parse condition ${v} for '@if.${info.attr}'`;
-    case "x-op":
-      return `Cannot parse value ${v} for <x ${info.op}>`;
-    case "handler-name":
-      return `Cannot parse handler name ${v}`;
-    case "handler-arg":
-      return `Cannot parse handler argument ${v}`;
-    case "macro-var":
-      return `Macro variable '^${info.name}' is not defined`;
-    default:
-      return `Cannot parse value ${v}`;
-  }
-}
-function tagDisplay(tag) {
-  return tag ? String(tag).toLowerCase() : null;
-}
-function fmtTagSuffix(info) {
-  const t = tagDisplay(info?.tag);
-  return t && t !== "x" ? ` on <${t}>` : "";
-}
-function fmtOriginSuffix(info) {
-  if (!info)
-    return "";
-  const parts = [];
-  if (info.originAttr) {
-    const branch = info.branch ? `[${info.branch}]` : "";
-    parts.push(`in ${info.originAttr}${branch}`);
-  }
-  if (info.handlerName) {
-    parts.push(`handler '${info.handlerName}'${info.argIndex !== undefined ? ` arg ${info.argIndex}` : ""}`);
-  }
-  const t = tagDisplay(info.tag);
-  if (t && t !== "x")
-    parts.push(`on <${t}>`);
-  return parts.length ? ` (${parts.join(", ")})` : "";
-}
-function fmtEventSuffix(info) {
-  if (info?.originAttr)
-    return ` in ${info.originAttr}`;
-  if (info?.eventName)
-    return ` in @on.${info.eventName}`;
-  return "";
-}
-function lintIdToMessage(id, info) {
-  switch (id) {
-    case "RENDER_IT_OUTSIDE_OF_LOOP":
-      return "<x render-it> used outside of a loop";
-    case "UNKNOWN_EVENT_MODIFIER": {
-      const mods = info.handler?.modifiers ?? [info.modifier];
-      const written = `@on.${info.name}+${mods.join("+")}`;
-      return `Unknown modifier '+${info.modifier}' in '${written}'`;
-    }
-    case "UNKNOWN_HANDLER_ARG_NAME":
-      return `Unknown handler argument '${info.name}'${fmtOriginSuffix(info)}`;
-    case "INPUT_HANDLER_NOT_IMPLEMENTED":
-      return `Input handler '${info.name}' is not implemented${fmtEventSuffix(info)}`;
-    case "INPUT_HANDLER_NOT_REFERENCED":
-      return `Input handler '${info.name}' is defined but never used — remove it or wire it to an @on.* event`;
-    case "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED":
-      return `Method '.${info.name}' is not implemented${fmtEventSuffix(info)}`;
-    case "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD":
-      return `'.${info.name}' is a method reference, but '${info.name}' is defined as an input handler${fmtEventSuffix(info)}`;
-    case "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER":
-      return `'${info.name}' is an input handler reference, but '${info.name}' is defined as a method${fmtEventSuffix(info)}`;
-    case "FIELD_VAL_NOT_DEFINED":
-      return `Field '.${info.name}' is not defined${fmtOriginSuffix(info)}`;
-    case "DUPLICATE_ATTR_DEFINITION": {
-      const sources = info.sources?.length ? ` (${info.sources.join(", ")})` : "";
-      const tag = info.tag ? ` on <${String(info.tag).toLowerCase()}>` : "";
-      return `Attribute '${info.name}' is set ${info.sources?.length ?? "multiple"} times${sources}${tag}`;
-    }
-    case "IF_NO_BRANCH_SET":
-      return `'@if.${info.attr}' has no '@then' or '@else' branch — add '@then="…"' or '@else="…"' (or both)${fmtTagSuffix(info)}`;
-    case "UNKNOWN_REQUEST_NAME":
-      return `Unknown request '!${info.name}'${fmtOriginSuffix(info)}`;
-    case "UNKNOWN_COMPONENT_NAME":
-      return `Unknown component '${info.name}'${fmtOriginSuffix(info)}`;
-    case "ALT_HANDLER_NOT_DEFINED":
-      return `Alter handler '${info.name}' is not defined${fmtOriginSuffix(info)}`;
-    case "ALT_HANDLER_NOT_REFERENCED":
-      return `Alter handler '${info.name}' is defined but never used — remove it or reference it from @when, @enrich-with, or @loop-with`;
-    case "UNKNOWN_MACRO_ARG":
-      return `Argument '${info.name}' is not declared in macro '${info.macroName}'`;
-    case "UNKNOWN_DIRECTIVE":
-      return `Unknown directive '@${info.name}=${JSON.stringify(info.value)}'${fmtTagSuffix(info)}`;
-    case "UNKNOWN_X_OP":
-      return `Unknown <x> op '${info.name}=${JSON.stringify(info.value)}'${fmtTagSuffix(info)}`;
-    case "UNKNOWN_X_ATTR":
-      return `Unknown attribute '${info.name}=${JSON.stringify(info.value)}' on <x ${info.op}>${fmtTagSuffix(info)}`;
-    case "MAYBE_DROP_AT_PREFIX": {
-      const written = info.value !== undefined ? `${info.name}=${JSON.stringify(info.value)}` : info.name;
-      return `'${written}' on <x> looks like a directive but is actually an x op/attr written with a leading '@'`;
-    }
-    case "BAD_VALUE":
-      return `${badValueMessage(info)}${fmtTagSuffix(info)}`;
-    case "UNSUPPORTED_EXPR_SYNTAX":
-      return `${unsupportedExprMessage(info)}${fmtTagSuffix(info)}`;
-    case "REDUNDANT_TEMPLATE_STRING":
-      return `Redundant template string — '{${info.simpler}}' should be just '${info.simpler}'${fmtOriginSuffix(info)}`;
-    case "UNKNOWN_COMPONENT_SPEC_KEY":
-      return `Unknown component spec key '${info.key}' — value will be ignored at runtime`;
-    case "HTML_TAG_NAME_HAS_UPPERCASE":
-      return `Tag <${info.raw}> will be lowercased to <${info.lowercased}>${fmtLocationSuffix(info)}`;
-    case "HTML_SVG_TAG_WILL_LOWERCASE":
-      return `SVG tag <${info.raw}> is not in the WHATWG case-correction list — will be lowercased to <${info.lowercased}>${fmtLocationSuffix(info)}`;
-    case "HTML_TAG_NOT_ALLOWED_IN_PARENT":
-      return `<${info.tag}> not allowed under <${info.parent ?? "?"}> in ${info.mode} — ${htmlActionPhrase(info.action, info.tag, info.parent)}${fmtLocationSuffix(info)}`;
-    case "HTML_TEXT_NOT_ALLOWED_IN_PARENT":
-      return `Non-whitespace text not allowed in ${info.mode}: ${JSON.stringify(info.snippet)}${fmtLocationSuffix(info)}`;
-    case "HTML_VOID_ELEMENT_HAS_CLOSE_TAG":
-      return `Void element <${info.tag}> has an explicit close tag${fmtLocationSuffix(info)}`;
-    case "HTML_DUPLICATE_FORM":
-      return `Nested <form> — the inner form will be dropped by the parser${fmtLocationSuffix(info)}`;
-    case "HTML_NESTED_INTERACTIVE":
-      return `<${info.tag}> nested inside another <${info.tag}> — adoption agency will reorder${fmtLocationSuffix(info)}`;
-    case "HTML_MISNESTED_FORMATTING":
-      return `Misnested formatting tag </${info.tag}> — adoption agency will reorder nodes${fmtLocationSuffix(info)}`;
-    case "HTML_UNEXPECTED_END_TAG":
-      return `Unexpected end tag </${info.tag}>${fmtLocationSuffix(info)}`;
-    case "HTML_UNCLOSED_BEFORE_END":
-      return `<${info.unclosed}> still open when </${info.tag}> was seen — implicitly closed${fmtLocationSuffix(info)}`;
-    case "HTML_DUPLICATE_ATTRIBUTE":
-      return `Duplicate attribute '${info.name}' — second occurrence dropped${fmtLocationSuffix(info)}`;
-    case "HTML_ATTRIBUTES_ON_END_TAG":
-      return `Attributes on end tag </${info.tag}> — dropped by the parser${fmtLocationSuffix(info)}`;
-    case "HTML_SELF_CLOSING_END_TAG":
-      return `Self-closing end tag </${info.tag}/> — trailing '/' is meaningless${fmtLocationSuffix(info)}`;
-    case "HTML_MISSING_ATTRIBUTE_VALUE":
-      return `Attribute '${info.name}' is missing a value${fmtLocationSuffix(info)}`;
-    case "HTML_CDATA_IN_HTML_NAMESPACE":
-      return `CDATA section in HTML namespace — reinterpreted as a bogus comment${fmtLocationSuffix(info)}`;
-    case "HTML_BOGUS_COMMENT":
-      return `Bogus comment — content dropped by the parser${fmtLocationSuffix(info)}`;
-    case "HTML_SVG_ATTR_WILL_LOWERCASE":
-      return `SVG attribute '${info.raw}' will be rewritten to '${info.canonical}'${fmtLocationSuffix(info)}`;
-    case "HTML_MATHML_ATTR_WILL_LOWERCASE":
-      return `MathML attribute '${info.raw}' will be rewritten to '${info.canonical}'${fmtLocationSuffix(info)}`;
-    case "LINT_ERROR":
-      return info.message;
-    default:
-      return id;
+import { parseArgs as parseArgs3 } from "node:util";
+
+// tools/cli/env.js
+init_anode();
+init_lint_check();
+import { JSDOM, VirtualConsole } from "jsdom";
+async function createNodeEnv() {
+  const virtualConsole = new VirtualConsole;
+  virtualConsole.forwardTo(console, { jsdomErrors: "none" });
+  virtualConsole.on("jsdomError", (err) => {
+    if (err?.message?.includes("Could not parse CSS stylesheet"))
+      return;
+    console.error(err.message);
+  });
+  const dom = new JSDOM("<!DOCTYPE html><html><head></head><body></body></html>", {
+    virtualConsole
+  });
+  const { document: document2, Text, Comment } = dom.window;
+  globalThis.document = document2;
+
+  class HeadlessParseContext extends ParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
   }
-}
-function suggestionToMessage(suggestion) {
-  if (!suggestion)
-    return null;
-  switch (suggestion.kind) {
-    case "replace-name":
-      return `did you mean '${suggestion.to}'?`;
-    case "drop-prefix":
-      return `did you mean '${suggestion.to}'? (drop the leading '${suggestion.from.slice(0, suggestion.from.length - suggestion.to.length)}')`;
-    case "add-prefix":
-      return `did you mean '${suggestion.to}'? (add the leading '${suggestion.to.slice(0, suggestion.to.length - suggestion.from.length)}')`;
-    case "remove":
-      return `remove ${suggestion.what}`;
-    case "rewrite":
-      return `use '${suggestion.to}' instead of '${suggestion.from}'`;
-    case "wrap":
-      return `wrap it in ${suggestion.to}`;
-    case "rephrase":
-      return suggestion.text ?? null;
-    default:
-      return null;
+
+  class HeadlessLintParseContext extends LintParseContext {
+    constructor() {
+      super(document2, Text, Comment);
+    }
   }
+  return {
+    document: dom.window.document,
+    ParseContext: HeadlessParseContext,
+    LintParseContext: HeadlessLintParseContext
+  };
 }
-function fmtLocationSuffix(info) {
-  const loc = info?.location;
-  if (!loc)
-    return "";
-  return ` at line ${loc.line}, col ${loc.column}`;
+
+// tools/cli/load.js
+import { resolve as resolve4 } from "node:path";
+async function loadAndNormalize(modulePath) {
+  const abs = resolve4(modulePath);
+  const mod = await import(abs);
+  const { normalized } = normalizeModule(mod, { path: abs });
+  return normalized;
 }
-function htmlActionPhrase(action, tag, parent) {
-  switch (action) {
-    case "ignored":
-      return `the parser will drop this <${tag}>`;
-    case "drop":
-      return `the parser will drop this <${tag}>`;
-    case "auto-close-implicit":
-      return `the parser will close <${parent ?? "?"}> first, then place <${tag}> as a sibling`;
-    case "foster-parent":
-      return `the parser will move <${tag}> outside <${parent ?? "?"}> (foster-parenting)`;
-    case "foreign-breakout":
-      return `the parser will exit foreign content and re-process <${tag}> in HTML mode`;
-    default:
-      return `parser action: ${action}`;
-  }
+
+// tools/cli/output.js
+import { writeFileSync } from "node:fs";
+
+// tools/format/cli.js
+var exports_cli = {};
+__export(exports_cli, {
+  supports: () => supports,
+  format: () => format
+});
+
+// tools/format/_dispatch.js
+function makeFormatter(name, table) {
+  return {
+    supports: new Set(Object.keys(table)),
+    async format(result, opts) {
+      const fn = table[result.constructor.name];
+      if (!fn) {
+        throw new Error(`${name} formatter missing dispatch for ${result.constructor.name}`);
+      }
+      return await fn(result, opts);
+    }
+  };
 }
 
 // tools/format/cli.js
+init_lint2();
 function fmtModuleInfo(info) {
   const lines = [];
   lines.push(`Module: ${info.path ?? "<in-memory>"}`);
@@ -14785,6 +15289,10 @@ function fmtComponentList(list) {
     for (const f of c.fields)
       lines.push(`  - ${f.name}: ${f.type}`);
   }
+  if (list.truncated) {
+    const remaining = list.total - list.items.length;
+    lines.push(`… ${remaining} more component(s) — re-run with \`--limit 0\` for all, or pass [name] to filter.`);
+  }
   return lines.join(`
 `);
 }
@@ -14792,12 +15300,18 @@ function fmtExampleIndex(idx) {
   if (idx.sections.length === 0)
     return "(no examples)";
   const lines = [];
+  let shown = 0;
   for (const s of idx.sections) {
     lines.push(`${s.title}${s.description ? ` — ${s.description}` : ""}`);
     for (const item of s.items) {
       lines.push(`  - ${item.title}${item.description ? ` — ${item.description}` : ""} [${item.componentName}${item.view !== "main" ? `/${item.view}` : ""}]`);
+      shown += 1;
     }
   }
+  if (idx.truncated) {
+    const remaining = idx.total - shown;
+    lines.push(`… ${remaining} more example(s) — re-run with \`--limit 0\` for all.`);
+  }
   return lines.join(`
 `);
 }
@@ -14919,12 +15433,70 @@ var { supports, format } = makeFormatter("cli", {
   TestReport: fmtTestReport
 });
 
+// tools/format/html.js
+var exports_html = {};
+__export(exports_html, {
+  supports: () => supports2,
+  format: () => format2
+});
+async function fmtRenderBatch2(result, { pretty = false } = {}) {
+  const prettify = pretty ? (await import("prettier")).format : null;
+  const parts = [];
+  for (const section of result.sections) {
+    parts.push(`<!-- === ${section.title} === -->`);
+    for (const item of section.items) {
+      if (item.error) {
+        parts.push(`<!-- ERROR ${item.title}: ${item.error.message} -->`);
+        continue;
+      }
+      let html = item.html;
+      if (prettify) {
+        try {
+          html = (await prettify(html, { parser: "html" })).trimEnd();
+        } catch {}
+      }
+      parts.push(`<!-- ${item.title} -->`);
+      parts.push(html);
+    }
+  }
+  return parts.join(`
+`);
+}
+var { supports: supports2, format: format2 } = makeFormatter("html", {
+  RenderBatch: fmtRenderBatch2
+});
+
+// tools/format/json.js
+var exports_json = {};
+__export(exports_json, {
+  supports: () => supports3,
+  format: () => format3
+});
+function replacer(_key, v) {
+  if (v instanceof Set)
+    return [...v];
+  return v;
+}
+function fmtJson(result, { pretty = false } = {}) {
+  return JSON.stringify(result, replacer, pretty ? 2 : 0);
+}
+var { supports: supports3, format: format3 } = makeFormatter("json", {
+  ModuleInfo: fmtJson,
+  ComponentList: fmtJson,
+  ExampleIndex: fmtJson,
+  ComponentDocs: fmtJson,
+  LintReport: fmtJson,
+  RenderBatch: fmtJson,
+  TestReport: fmtJson
+});
+
 // tools/format/md.js
 var exports_md = {};
 __export(exports_md, {
-  supports: () => supports2,
-  format: () => format2
+  supports: () => supports4,
+  format: () => format4
 });
+init_lint2();
 function fmtComponentDocs2(docs) {
   const lines = [];
   for (const comp of docs.items) {
@@ -14958,7 +15530,7 @@ function fmtComponentDocs2(docs) {
   return lines.join(`
 `);
 }
-async function fmtRenderBatch2(batch, { pretty = false } = {}) {
+async function fmtRenderBatch3(batch, { pretty = false } = {}) {
   const prettify = pretty ? (await import("prettier")).format : null;
   const lines = [];
   for (const section of batch.sections) {
@@ -15105,9 +15677,9 @@ function fmtTestReport2(report) {
   return lines.join(`
 `);
 }
-var { supports: supports2, format: format2 } = makeFormatter("md", {
+var { supports: supports4, format: format4 } = makeFormatter("md", {
   ComponentDocs: fmtComponentDocs2,
-  RenderBatch: fmtRenderBatch2,
+  RenderBatch: fmtRenderBatch3,
   ExampleIndex: fmtExampleIndex2,
   LintReport: fmtLintReport2,
   ModuleInfo: fmtModuleInfo2,
@@ -15115,77 +15687,34 @@ var { supports: supports2, format: format2 } = makeFormatter("md", {
   TestReport: fmtTestReport2
 });
 
-// tools/format/json.js
-var exports_json = {};
-__export(exports_json, {
-  supports: () => supports3,
-  format: () => format3
-});
-function replacer(_key, v) {
-  if (v instanceof Set)
-    return [...v];
-  return v;
-}
-function fmtJson(result, { pretty = false } = {}) {
-  return JSON.stringify(result, replacer, pretty ? 2 : 0);
-}
-var { supports: supports3, format: format3 } = makeFormatter("json", {
-  ModuleInfo: fmtJson,
-  ComponentList: fmtJson,
-  ExampleIndex: fmtJson,
-  ComponentDocs: fmtJson,
-  LintReport: fmtJson,
-  RenderBatch: fmtJson,
-  TestReport: fmtJson
-});
-
-// tools/format/html.js
-var exports_html = {};
-__export(exports_html, {
-  supports: () => supports4,
-  format: () => format4
-});
-async function fmtRenderBatch3(result, { pretty = false } = {}) {
-  const prettify = pretty ? (await import("prettier")).format : null;
-  const parts = [];
-  for (const section of result.sections) {
-    parts.push(`<!-- === ${section.title} === -->`);
-    for (const item of section.items) {
-      if (item.error) {
-        parts.push(`<!-- ERROR ${item.title}: ${item.error.message} -->`);
-        continue;
-      }
-      let html = item.html;
-      if (prettify) {
-        try {
-          html = (await prettify(html, { parser: "html" })).trimEnd();
-        } catch {}
-      }
-      parts.push(`<!-- ${item.title} -->`);
-      parts.push(html);
-    }
-  }
-  return parts.join(`
-`);
-}
-var { supports: supports4, format: format4 } = makeFormatter("html", {
-  RenderBatch: fmtRenderBatch3
-});
-
 // tools/format/index.js
 var FORMATTERS = { cli: exports_cli, md: exports_md, json: exports_json, html: exports_html };
 function pickFormatter(name) {
   const f = FORMATTERS[name];
   if (!f) {
-    throw new Error(`Unknown format: ${name}. Available: ${Object.keys(FORMATTERS).join(", ")}`);
+    const err = new Error(`Unknown format '${name}'. Valid formats: ${Object.keys(FORMATTERS).join(", ")}`);
+    err.code = "ERR_FORMAT_UNKNOWN";
+    err.formatName = name;
+    err.validFormats = Object.keys(FORMATTERS);
+    throw err;
   }
   return f;
 }
+function formattersSupporting(kind) {
+  return Object.entries(FORMATTERS).filter(([, f]) => f.supports?.has(kind)).map(([name]) => name);
+}
 async function formatResult(formatName, result, options = {}) {
   const f = pickFormatter(formatName);
   const kind = result.constructor.name;
   if (!f.supports?.has(kind)) {
-    throw new Error(`Formatter "${formatName}" does not support ${kind}`);
+    const supported = formattersSupporting(kind);
+    const supportedTail = supported.length ? ` Use one of: ${supported.join(", ")}.` : "";
+    const err = new Error(`Format '${formatName}' does not support ${kind}.${supportedTail}`);
+    err.code = "ERR_FORMAT_UNSUPPORTED";
+    err.formatName = formatName;
+    err.resultKind = kind;
+    err.supportedFormats = supported;
+    throw err;
   }
   return await f.format(result, options);
 }
@@ -15206,7 +15735,7 @@ async function emit(result, { format: format5, pretty, output }) {
 
 // tools/cli/with-module.js
 async function runCommand(cmd, argv, globalOpts) {
-  const parsed = parseArgs2({
+  const parsed = parseArgs3({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
@@ -15229,23 +15758,29 @@ async function runCommand(cmd, argv, globalOpts) {
 // tools/tutuca.js
 var NO_MODULE_COMMANDS = {
   help: exports_help,
-  "install-skill": exports_install_skill
+  feedback: exports_feedback,
+  "install-skill": exports_install_skill,
+  "agent-context": exports_agent_context
 };
-function usageError(msg) {
-  process.stderr.write(`tutuca: ${msg}
-Run \`tutuca help\` for usage.
-`);
-  process.exit(1);
-}
+var VALID_FORMATS = ["cli", "md", "json", "html"];
+var GLOBAL_FLAGS2 = ["format", "output", "pretty", "module", "json", "help", "no-color"];
 function extractGlobals(argv) {
   const rest = [];
-  const opts = { format: null, output: null, pretty: false, module: null, help: false };
+  const opts = {
+    format: null,
+    output: null,
+    pretty: false,
+    module: null,
+    help: false
+  };
   for (let i = 0;i < argv.length; i++) {
     const a = argv[i];
     if (a === "-f" || a === "--format") {
       opts.format = argv[++i];
     } else if (a.startsWith("--format=")) {
       opts.format = a.slice("--format=".length);
+    } else if (a === "--json") {
+      opts.format = "json";
     } else if (a === "-o" || a === "--output") {
       opts.output = argv[++i];
     } else if (a.startsWith("--output=")) {
@@ -15262,41 +15797,59 @@ function extractGlobals(argv) {
       rest.push(a);
     }
   }
+  if (opts.format != null && !VALID_FORMATS.includes(opts.format)) {
+    emitError(opts, {
+      code: CODES.FORMAT_UNKNOWN,
+      message: `Unknown format '${opts.format}'`,
+      suggestion: didYouMean(opts.format, VALID_FORMATS),
+      hint: `Valid formats: ${VALID_FORMATS.join(", ")}`
+    });
+  }
   return { opts, rest };
 }
+function dispatchKnownCommands() {
+  return [...Object.keys(COMMANDS), ...Object.keys(NO_MODULE_COMMANDS)];
+}
 async function main() {
   const { opts, rest } = extractGlobals(process.argv.slice(2));
   if (rest.length === 0 || opts.help && rest.length === 0) {
-    await run2([], opts);
+    await run4([], opts);
     return;
   }
-  let command;
-  let commandArgs;
-  if (NO_MODULE_COMMANDS[rest[0]]) {
-    command = rest[0];
-    commandArgs = rest.slice(1);
-  } else if (opts.module) {
-    command = rest[0];
-    commandArgs = rest.slice(1);
-  } else {
-    if (rest.length < 2)
-      return usageError("expected <module-path> <command>");
-    opts.module = rest[0];
-    command = rest[1];
-    commandArgs = rest.slice(2);
-  }
+  const command = rest[0];
   if (NO_MODULE_COMMANDS[command]) {
-    const args = opts.help ? [...commandArgs, "--help"] : commandArgs;
+    const commandArgs2 = rest.slice(1);
+    const args = opts.help ? [...commandArgs2, "--help"] : commandArgs2;
     await NO_MODULE_COMMANDS[command].run(args, opts);
     return;
   }
   if (opts.help) {
-    await run2([command], opts);
+    await run4([command], opts);
     return;
   }
   const cmd = COMMANDS[command];
-  if (!cmd)
-    return usageError(`unknown command: ${command}`);
+  if (!cmd) {
+    const known = dispatchKnownCommands();
+    emitError(opts, {
+      code: CODES.USAGE_UNKNOWN_COMMAND,
+      message: `Unknown command '${command}'`,
+      suggestion: didYouMean(command, known),
+      hint: "Run `tutuca help` for the full reference."
+    });
+  }
+  let commandArgs;
+  if (opts.module) {
+    commandArgs = rest.slice(1);
+  } else if (rest.length < 2 || rest[1].startsWith("-")) {
+    emitError(opts, {
+      code: CODES.USAGE_MISSING_MODULE,
+      message: `'${command}' requires a module path`,
+      hint: `Pass it as the second positional: \`tutuca ${command} <module-path>\`, or use --module=<path>.`
+    });
+  } else {
+    opts.module = rest[1];
+    commandArgs = rest.slice(2);
+  }
   try {
     await runCommand(cmd, commandArgs, opts);
   } catch (e) {
@@ -15306,21 +15859,56 @@ async function main() {
         parts.push(opts.module);
       if (e.where)
         parts.push(`@ ${e.where}`);
-      const prefix = parts.length ? `[${parts.join(" ")}] ` : "";
-      process.stderr.write(`tutuca: ${prefix}${e.message}
-`);
-      process.exit(1);
+      emitError(opts, {
+        code: CODES.MODULE_SHAPE_MISMATCH,
+        message: e.message,
+        where: parts.length ? parts.join(" ") : null
+      });
+    }
+    if (e?.code === "ERR_FORMAT_UNKNOWN") {
+      emitError(opts, {
+        code: CODES.FORMAT_UNKNOWN,
+        message: e.message,
+        suggestion: didYouMean(e.formatName, e.validFormats ?? VALID_FORMATS)
+      });
+    }
+    if (e?.code === "ERR_FORMAT_UNSUPPORTED") {
+      emitError(opts, {
+        code: CODES.FORMAT_UNSUPPORTED,
+        message: e.message,
+        suggestion: e.supportedFormats?.length ? { kind: "rewrite", from: e.formatName, to: e.supportedFormats[0] } : null
+      });
     }
     if (e?.code?.startsWith?.("ERR_PARSE_ARGS_")) {
-      process.stderr.write(`tutuca: ${e.message}
-`);
-      process.exit(1);
+      const validFlags = [...Object.keys(cmd.parseOptions ?? {}), ...GLOBAL_FLAGS2];
+      const shape = parseArgsErrorShape(e, validFlags);
+      emitError(opts, {
+        ...shape,
+        hint: shape.hint ?? `Run \`tutuca help ${command}\` for valid flags.`
+      });
     }
     throw e;
   }
 }
 main().catch((e) => {
-  process.stderr.write(`${e.stack ?? e.message ?? e}
+  const wantsJson = process.argv.includes("--json") || process.argv.includes("--format=json") || process.argv.includes("-f=json") || (() => {
+    const i = process.argv.findIndex((a) => a === "-f" || a === "--format");
+    return i >= 0 && process.argv[i + 1] === "json";
+  })();
+  if (wantsJson) {
+    const envelope = {
+      error: {
+        code: e?.code ?? CODES.INTERNAL,
+        message: e?.message ?? String(e)
+      }
+    };
+    if (e?.where)
+      envelope.error.where = e.where;
+    process.stderr.write(`${JSON.stringify(envelope)}
+`);
+  } else {
+    process.stderr.write(`${e.stack ?? e.message ?? e}
 `);
+  }
   process.exit(1);
 });