tutuca 0.9.30 → 0.9.32

package/README.md

@@ -95,6 +95,7 @@ tutuca help [command]
 | `lint [name]` | Run lint checks — all, or one by name (exit 2 on errors) |
 | `render [name] [--title t] [--view v]` | Render examples to HTML |
 | `doctor` | Lint + render smoke test over the whole module |
+| `install-skill [--user] [--force]` | Install the tutuca Claude Code skill (no module path needed) |
 
 Global flags: `-f, --format <cli\|md\|json\|html>`, `-o, --output <file>`, `--pretty`, `-h, --help`.
 
@@ -138,6 +139,27 @@ The invocation stays short even without wrapping, but common patterns:
 - **`justfile` / `Makefile`** — one recipe per subcommand, passing through positionals
 - **Programmatic** — `import "tutuca/cli"` (the bundled entry) for custom build integration
 
+## Use with Claude Code
+
+Tutuca ships an LLM-facing reference (`SKILL.md` + `core.md` / `cli.md` /
+`advanced.md`) packaged as a [Claude Code skill](https://docs.claude.com/en/docs/claude-code/skills).
+Once installed, Claude auto-loads it whenever a session touches tutuca
+components, views, macros, or the CLI.
+
+```sh
+# project-scoped: writes ./.claude/skills/tutuca/ (commit it for the team)
+npx tutuca install-skill
+
+# or user-scoped: writes ~/.claude/skills/tutuca/
+npx tutuca install-skill --user
+
+# overwrite an existing install
+npx tutuca install-skill --force
+```
+
+The skill content is generated from `docs/llm/`, so the same reference
+runs locally (`tutuca <module> doctor`) and inside Claude.
+
 ## License
 
 MIT

package/dist/tutuca-cli.js

@@ -1147,6 +1147,8 @@ class AttrParser {
       this.parseThen(s);
     else if (directiveName.startsWith("else."))
       this.parseElse(s);
+    else
+      this.px.onParseIssue("unknown-directive", { name: directiveName, value: s });
   }
   _parseWhen(s) {
     if (this.eachAttr !== null)
@@ -1332,6 +1334,30 @@ function optimizeNode(node) {
   node.optimize();
   return node;
 }
+function processXExtras(node, attrs, opName, startIdx, px) {
+  const consumed = X_OP_CONSUMED[opName];
+  const wrappable = X_OP_WRAPPABLE.has(opName);
+  const wrappers = [];
+  for (let i = startIdx;i < attrs.length; i++) {
+    const a = attrs[i];
+    const aName = a.name;
+    if (consumed.has(aName))
+      continue;
+    if (wrappable && X_ATTR_WRAPPERS[aName]) {
+      wrappers.push([X_ATTR_WRAPPERS[aName], vp.parseCondValue(a.value, px)]);
+      continue;
+    }
+    const issueInfo = { op: opName, name: aName, value: a.value };
+    px.onParseIssue("unknown-x-attr", issueInfo);
+  }
+  for (let i = wrappers.length - 1;i >= 0; i--) {
+    const [Cls, val] = wrappers[i];
+    const wrapper = px.addNodeIf(Cls, val, node);
+    if (wrapper !== null)
+      node = wrapper;
+  }
+  return node;
+}
 function wrap(node, px, wrappers) {
   if (wrappers) {
     for (let i = wrappers.length - 1;i >= 0; i--) {
@@ -1394,7 +1420,7 @@ class ParseContext {
   parseHTML(html) {
     const t = this.document.createElement("template");
     t.innerHTML = html;
-    return Array.from(t.content.childNodes);
+    return t.content.childNodes;
   }
   addNodeIf(Class, val, extra) {
     if (val !== null) {
@@ -1438,6 +1464,9 @@ class ParseContext {
     return this.nodes[id] ?? null;
   }
   onAttributes(_attrs, _wrapperAttrs, _textChild, _isMacroCall) {}
+  onParseIssue(kind, info) {
+    console.warn(`tutuca parse issue [${kind}]`, info);
+  }
 }
 function condenseChildsWhites(childs) {
   if (childs.length === 0)
@@ -1517,7 +1546,7 @@ function compileModifiers(eventName, names) {
     return w(this, f, args, ctx);
   };
 }
-var TextNode, CommentNode, ChildsNode, DomNode, FragmentNode, maybeFragment = (xs) => xs.length === 1 ? xs[0] : new FragmentNode(xs), VALID_NODE_RE, ANode, MacroNode, RenderViewId, RenderNode, RenderItNode, RenderEachNode, RenderTextNode, RenderOnceNode, WrapperNode, ShowNode, HideNode, PushViewNameNode, SlotNode, ScopeNode, EachNode, filterAlwaysTrue = (_v, _k, _seq) => true, nullLoopWith = (seq) => ({ seq }), WRAPPER_NODES, _htmlBlockTags = "ADDRESS,ARTICLE,ASIDE,BLOCKQUOTE,CAPTION,COL,COLGROUP,DETAILS,DIALOG,DIV,DD,DL,DT,FIELDSET,FIGCAPTION,FIGURE,FOOTER,FORM,H1,H2,H3,H4,H5,H6,HEADER,HGROUP,HR,LEGEND,LI,MAIN,MENU,NAV,OL,P,PRE,SECTION,SUMMARY,TABLE,TBODY,TD,TFOOT,TH,THEAD,TR,UL", HTML_BLOCK_TAGS, isBlockDomNode = (n) => {
+var TextNode, CommentNode, ChildsNode, DomNode, FragmentNode, maybeFragment = (xs) => xs.length === 1 ? xs[0] : new FragmentNode(xs), VALID_NODE_RE, ANode, MacroNode, RenderViewId, RenderNode, RenderItNode, RenderEachNode, RenderTextNode, RenderOnceNode, WrapperNode, ShowNode, HideNode, PushViewNameNode, SlotNode, ScopeNode, EachNode, filterAlwaysTrue = (_v, _k, _seq) => true, nullLoopWith = (seq) => ({ seq }), X_OP_CONSUMED, X_OP_WRAPPABLE, X_ATTR_WRAPPERS, WRAPPER_NODES, _htmlBlockTags = "ADDRESS,ARTICLE,ASIDE,BLOCKQUOTE,CAPTION,COL,COLGROUP,DETAILS,DIALOG,DIV,DD,DL,DT,FIELDSET,FIGCAPTION,FIGURE,FOOTER,FORM,H1,H2,H3,H4,H5,H6,HEADER,HGROUP,HR,LEGEND,LI,MAIN,MENU,NAV,OL,P,PRE,SECTION,SUMMARY,TABLE,TBODY,TD,TFOOT,TH,THEAD,TR,UL", HTML_BLOCK_TAGS, isBlockDomNode = (n) => {
   const node = n instanceof FragmentNode ? n.childs[0] : n;
   return node instanceof DomNode && HTML_BLOCK_TAGS.has(node.tagName);
 }, isMac, fwdIfCtxPred = (pred) => (w) => (that, f, args, ctx) => pred(ctx) ? w(that, f, args, ctx) : that, fwdIfKey = (keyName) => fwdIfCtxPred((ctx) => ctx.e.key === keyName), fwdCtrl, fwdMeta, fwdAlt, metaWraps, MOD_WRAPPERS_BY_EVENT, identityModifierWrapper = (f, _ctx) => f;
@@ -1614,7 +1643,21 @@ var init_anode = __esm(() => {
       return this.val.toPathItem();
     }
     static parse(html, px) {
-      return ANode.fromDOM(px.parseHTML(html)[0] ?? new px.Text(""), px);
+      const nodes = px.parseHTML(html);
+      if (nodes.length === 0)
+        return new CommentNode("Empty View in ANode.parse");
+      if (nodes.length === 1)
+        return ANode.fromDOM(nodes[0], px);
+      const childs = [];
+      for (let i = 0;i < nodes.length; i++) {
+        const child = ANode.fromDOM(nodes[i], px);
+        if (child !== null)
+          childs.push(child);
+      }
+      const trimmed = condenseChildsWhites(childs);
+      if (trimmed.length === 0)
+        return new CommentNode("Empty View in ANode.parse");
+      return maybeFragment(trimmed);
     }
     static fromDOM(node, px) {
       if (node instanceof px.Text)
@@ -1629,27 +1672,37 @@ var init_anode = __esm(() => {
       if (tag === "X" || isPseudoX) {
         if (attrs.length === 0)
           return maybeFragment(childs);
-        const { name, value } = attrs[isPseudoX ? 1 : 0];
+        const opIdx = isPseudoX ? 1 : 0;
+        const { name, value } = attrs[opIdx];
         const as = attrs.getNamedItem("as")?.value ?? null;
+        let node2;
         switch (name) {
           case "slot":
-            return new SlotNode(null, vp.const(value), maybeFragment(childs));
-          case "text": {
-            const v = vp.parseText(value, px);
-            return v !== null ? new RenderTextNode(null, v) : null;
-          }
+            node2 = new SlotNode(null, vp.const(value), maybeFragment(childs));
+            break;
+          case "text":
+            node2 = px.addNodeIf(RenderTextNode, vp.parseText(value, px));
+            break;
           case "render":
-            return px.addNodeIf(RenderNode, vp.parseRender(value, px), as);
+            node2 = px.addNodeIf(RenderNode, vp.parseRender(value, px), as);
+            break;
           case "render-it":
-            return px.addNodeIf(RenderItNode, vp.bindValIt, as);
+            node2 = px.addNodeIf(RenderItNode, vp.bindValIt, as);
+            break;
           case "render-each":
-            return RenderEachNode.parse(px, vp, value, as, attrs);
+            node2 = RenderEachNode.parse(px, vp, value, as, attrs);
+            break;
           case "show":
-            return px.addNodeIf(ShowNode, vp.parseCondValue(value, px), maybeFragment(childs));
+            node2 = px.addNodeIf(ShowNode, vp.parseCondValue(value, px), maybeFragment(childs));
+            break;
           case "hide":
-            return px.addNodeIf(HideNode, vp.parseCondValue(value, px), maybeFragment(childs));
+            node2 = px.addNodeIf(HideNode, vp.parseCondValue(value, px), maybeFragment(childs));
+            break;
+          default:
+            px.onParseIssue("unknown-x-op", { name, value });
+            return new CommentNode(`Error: InvalidSpecialTagOp ${name}=${value}`);
         }
-        return new CommentNode(`Error: InvalidSpecialTagOp ${name}=${value}`);
+        return processXExtras(node2, attrs, name, (isPseudoX ? 1 : 0) + 1, px);
       } else if (tag.charCodeAt(1) === 58 && tag.charCodeAt(0) === 88) {
         const macroName = tag.slice(2).toLowerCase();
         if (macroName === "slot") {
@@ -1833,6 +1886,17 @@ var init_anode = __esm(() => {
     }
     static register = true;
   };
+  X_OP_CONSUMED = {
+    slot: new Set,
+    text: new Set,
+    render: new Set(["as"]),
+    "render-it": new Set(["as"]),
+    "render-each": new Set(["as", "when", "loop-with"]),
+    show: new Set,
+    hide: new Set
+  };
+  X_OP_WRAPPABLE = new Set(["text", "render", "render-it", "render-each"]);
+  X_ATTR_WRAPPERS = { show: ShowNode, hide: HideNode };
   WRAPPER_NODES = {
     slot: SlotNode,
     show: ShowNode,
@@ -2025,7 +2089,11 @@ class ComponentStack {
     }
   }
   registerMacros(macros) {
-    Object.assign(this.macros, macros);
+    for (const key in macros) {
+      const lower = key.toLowerCase();
+      console.assert(this.macros[lower] === undefined, "macro key collision", lower);
+      this.macros[lower] = macros[key];
+    }
   }
   getCompFor(v) {
     return this.comps.getCompFor(v);
@@ -2069,11 +2137,29 @@ function checkComponent(Comp, lx = new LintContext) {
   });
 }
 function checkView(lx, view, Comp, referencedAlters, referencedComputed) {
+  checkParseIssues(lx, view);
   checkRenderItInLoop(lx, view);
   checkEventModifiers(lx, view);
   checkKnownHandlerNames(lx, view, Comp, referencedAlters, referencedComputed);
   checkMacroCallArgs(lx, view, Comp);
 }
+function checkParseIssues(lx, view) {
+  const issues = view.ctx.parseIssues;
+  if (!issues)
+    return;
+  for (const { kind, info } of issues) {
+    const id = PARSE_ISSUE_KIND_TO_LINT_ID[kind];
+    if (!id)
+      continue;
+    lx.error(id, info);
+    const known = AT_PREFIX_HINT_KNOWN_BY_KIND[kind];
+    if (known && info.name?.startsWith("@")) {
+      const suggestion = info.name.slice(1);
+      if (known.has(suggestion))
+        lx.hint(MAYBE_DROP_AT_PREFIX, { ...info, suggestion });
+    }
+  }
+}
 function checkMacroCallArgs(lx, view, Comp) {
   const { scope } = Comp;
   for (const macroNode of view.ctx.macroNodes) {
@@ -2083,7 +2169,10 @@ function checkMacroCallArgs(lx, view, Comp) {
     const { defaults } = macro;
     for (const argName in macroNode.attrs) {
       if (!(argName in defaults)) {
-        lx.error(UNKNOWN_MACRO_ARG, { name: argName, macroName: macroNode.name });
+        lx.error(UNKNOWN_MACRO_ARG, {
+          name: argName,
+          macroName: macroNode.name
+        });
       }
     }
   }
@@ -2244,7 +2333,7 @@ function checkConsistentAttrVal(lx, val, fields, proto, computed, scope, alter,
     if (alter[val.name] === undefined) {
       lx.error(ALT_HANDLER_NOT_DEFINED, { name: val.name });
     }
-  } else if (valName !== "ConstVal" && valName !== "BindVal") {
+  } else if (valName !== "ConstVal" && valName !== "BindVal" && valName !== "DynVal") {
     console.log(val);
   }
 }
@@ -2359,9 +2448,28 @@ class LintContext {
     this.reports.push({ id, info, level, context: { ...this.frame } });
   }
 }
-var ALT_HANDLER_NOT_DEFINED = "ALT_HANDLER_NOT_DEFINED", ALT_HANDLER_NOT_REFERENCED = "ALT_HANDLER_NOT_REFERENCED", RENDER_IT_OUTSIDE_OF_LOOP = "RENDER_IT_OUTSIDE_OF_LOOP", UNKNOWN_EVENT_MODIFIER = "UNKNOWN_EVENT_MODIFIER", UNKNOWN_HANDLER_ARG_NAME = "UNKNOWN_HANDLER_ARG_NAME", INPUT_HANDLER_NOT_IMPLEMENTED = "INPUT_HANDLER_NOT_IMPLEMENTED", INPUT_HANDLER_NOT_REFERENCED = "INPUT_HANDLER_NOT_REFERENCED", INPUT_HANDLER_METHOD_NOT_IMPLEMENTED = "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED", INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD = "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD", INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER = "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER", FIELD_VAL_NOT_DEFINED = "FIELD_VAL_NOT_DEFINED", COMPUTED_VAL_NOT_DEFINED = "COMPUTED_VAL_NOT_DEFINED", COMPUTED_NOT_REFERENCED = "COMPUTED_NOT_REFERENCED", DUPLICATE_ATTR_DEFINITION = "DUPLICATE_ATTR_DEFINITION", UNKNOWN_REQUEST_NAME = "UNKNOWN_REQUEST_NAME", UNKNOWN_COMPONENT_NAME = "UNKNOWN_COMPONENT_NAME", UNKNOWN_MACRO_ARG = "UNKNOWN_MACRO_ARG", LEVEL_WARN = "warn", LEVEL_ERROR = "error", LEVEL_HINT = "hint", NO_WRAPPERS, KNOWN_HANDLER_NAMES, LintParseContext;
+var ALT_HANDLER_NOT_DEFINED = "ALT_HANDLER_NOT_DEFINED", ALT_HANDLER_NOT_REFERENCED = "ALT_HANDLER_NOT_REFERENCED", RENDER_IT_OUTSIDE_OF_LOOP = "RENDER_IT_OUTSIDE_OF_LOOP", UNKNOWN_EVENT_MODIFIER = "UNKNOWN_EVENT_MODIFIER", UNKNOWN_HANDLER_ARG_NAME = "UNKNOWN_HANDLER_ARG_NAME", INPUT_HANDLER_NOT_IMPLEMENTED = "INPUT_HANDLER_NOT_IMPLEMENTED", INPUT_HANDLER_NOT_REFERENCED = "INPUT_HANDLER_NOT_REFERENCED", INPUT_HANDLER_METHOD_NOT_IMPLEMENTED = "INPUT_HANDLER_METHOD_NOT_IMPLEMENTED", INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD = "INPUT_HANDLER_FOR_INPUT_HANDLER_METHOD", INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER = "INPUT_HANDLER_METHOD_FOR_INPUT_HANDLER", FIELD_VAL_NOT_DEFINED = "FIELD_VAL_NOT_DEFINED", COMPUTED_VAL_NOT_DEFINED = "COMPUTED_VAL_NOT_DEFINED", COMPUTED_NOT_REFERENCED = "COMPUTED_NOT_REFERENCED", DUPLICATE_ATTR_DEFINITION = "DUPLICATE_ATTR_DEFINITION", UNKNOWN_REQUEST_NAME = "UNKNOWN_REQUEST_NAME", UNKNOWN_COMPONENT_NAME = "UNKNOWN_COMPONENT_NAME", UNKNOWN_MACRO_ARG = "UNKNOWN_MACRO_ARG", UNKNOWN_DIRECTIVE = "UNKNOWN_DIRECTIVE", UNKNOWN_X_OP = "UNKNOWN_X_OP", UNKNOWN_X_ATTR = "UNKNOWN_X_ATTR", MAYBE_DROP_AT_PREFIX = "MAYBE_DROP_AT_PREFIX", PARSE_ISSUE_KIND_TO_LINT_ID, X_KNOWN_OP_NAMES, X_KNOWN_ATTR_NAMES, AT_PREFIX_HINT_KNOWN_BY_KIND, LEVEL_WARN = "warn", LEVEL_ERROR = "error", LEVEL_HINT = "hint", NO_WRAPPERS, KNOWN_HANDLER_NAMES, LintParseContext;
 var init_lint_check = __esm(() => {
   init_anode();
+  PARSE_ISSUE_KIND_TO_LINT_ID = {
+    "unknown-directive": UNKNOWN_DIRECTIVE,
+    "unknown-x-op": UNKNOWN_X_OP,
+    "unknown-x-attr": UNKNOWN_X_ATTR
+  };
+  X_KNOWN_OP_NAMES = new Set([
+    "slot",
+    "text",
+    "render",
+    "render-it",
+    "render-each",
+    "show",
+    "hide"
+  ]);
+  X_KNOWN_ATTR_NAMES = new Set(["as", "when", "loop-with", "show", "hide"]);
+  AT_PREFIX_HINT_KNOWN_BY_KIND = {
+    "unknown-x-op": X_KNOWN_OP_NAMES,
+    "unknown-x-attr": X_KNOWN_ATTR_NAMES
+  };
   NO_WRAPPERS = {};
   KNOWN_HANDLER_NAMES = new Set([
     "value",
@@ -2387,10 +2495,14 @@ var init_lint_check = __esm(() => {
     constructor(document2, Text, Comment) {
       super(document2, Text, Comment);
       this.attrs = [];
+      this.parseIssues = [];
     }
     onAttributes(attrs, wrapperAttrs, textChild, isMacroCall = false) {
       this.attrs.push({ attrs, wrapperAttrs, textChild, isMacroCall });
     }
+    onParseIssue(kind, info) {
+      this.parseIssues.push({ kind, info });
+    }
   };
 });
 
@@ -7719,7 +7831,7 @@ class Renderer {
     this.cache = new WeakMapDomCache;
   }
   getSeqInfo(seq) {
-    return isIndexed(seq) ? imIndexedIter : isKeyed(seq) ? imKeyedIter : seqInfoByClass.get(seq?.constructor) ?? unkIter;
+    return isIndexed(seq) ? imIndexedIter : isKeyed(seq) ? imKeyedIter : seq?.[SEQ_INFO] ?? unkIter;
   }
   renderTag(tag, attrs, childs) {
     return h(tag, attrs, childs);
@@ -7835,12 +7947,12 @@ var DATASET_ATTRS, imIndexedIter = (seq, visit) => {
 }, imKeyedIter = (seq, visit) => {
   for (const [k, v] of seq.toSeq().entries())
     visit(k, v, "sk");
-}, unkIter = () => {}, seqInfoByClass;
+}, unkIter = () => {}, SEQ_INFO;
 var init_renderer = __esm(() => {
   init_immutable();
   init_vdom();
   DATASET_ATTRS = ["nid", "cid", "eid", "vid", "si", "sk"];
-  seqInfoByClass = new Map;
+  SEQ_INFO = Symbol.for("tutuca.seqInfo");
 });
 
 // src/util/render.js
@@ -8040,11 +8152,105 @@ var init__registry = __esm(() => {
   };
 });
 
+// tools/cli/commands/install-skill.js
+var exports_install_skill = {};
+__export(exports_install_skill, {
+  run: () => run,
+  describe: () => describe
+});
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { fileURLToPath } from "node:url";
+function findSkillDir() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [resolve(here, "..", "..", "..", "skill"), resolve(here, "..", "skill")];
+  for (const c of candidates) {
+    if (existsSync(resolve(c, "SKILL.md")))
+      return c;
+  }
+  return null;
+}
+function targetDir(scope) {
+  if (scope === "user")
+    return resolve(homedir(), ".claude/skills/tutuca");
+  return resolve(process.cwd(), ".claude/skills/tutuca");
+}
+async function run(argv) {
+  const parsed = parseArgs({
+    args: argv,
+    options: {
+      user: { type: "boolean", default: false },
+      project: { 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] [--force]
+` + `
+` + `  Copies SKILL.md + core.md + cli.md + advanced.md into
+` + `  .claude/skills/tutuca/. Defaults to --project (cwd).
+` + `  --user installs at ~/.claude/skills/tutuca/.
+` + `  --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 scope = parsed.values.user ? "user" : "project";
+  const target = targetDir(scope);
+  const src = findSkillDir();
+  if (!src) {
+    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);
+  }
+  if (existsSync(target) && !parsed.values.force) {
+    const existing = readdirSync(target).filter((n) => SKILL_FILES.includes(n));
+    if (existing.length > 0) {
+      process.stderr.write(`tutuca: ${target} already contains skill files. Re-run with --force to overwrite.
+`);
+      process.exit(1);
+    }
+  }
+  mkdirSync(target, { recursive: true });
+  for (const name of SKILL_FILES) {
+    const from = resolve(src, name);
+    if (!existsSync(from)) {
+      process.stderr.write(`tutuca: missing skill asset: ${from}
+`);
+      process.exit(1);
+    }
+    const buf = readFileSync(from);
+    writeFileSync(resolve(target, name), buf);
+  }
+  const rel = scope === "project" ? ".claude/skills/tutuca" : target;
+  process.stdout.write(`installed tutuca skill → ${rel}
+`);
+  process.stdout.write(`Open a Claude Code session in this directory to use it.
+`);
+}
+var describe = "Install the tutuca Claude Code skill into .claude/skills/tutuca/.", SKILL_FILES;
+var init_install_skill = __esm(() => {
+  SKILL_FILES = ["SKILL.md", "core.md", "cli.md", "advanced.md"];
+});
+
 // tools/tutuca.js
 init__registry();
 
 // tools/cli/commands/help.js
-var describe = "Show usage. `help <command>` for per-command detail.";
+var exports_help = {};
+__export(exports_help, {
+  run: () => run2,
+  describe: () => describe2
+});
+var describe2 = "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.
 
@@ -8122,6 +8328,11 @@ COMMANDS (no module required)
       Without [command]: prints this full reference.
       With [command]: prints that command's one-line description.
 
+  install-skill [--user | --project] [--force]
+      Copy the bundled Claude Code skill (SKILL.md + core/cli/advanced.md)
+      into .claude/skills/tutuca/. Default scope is --project (cwd);
+      --user installs at ~/.claude/skills/tutuca/. --force overwrites.
+
 GLOBAL FLAGS
   -f, --format <cli|md|json|html>
       Output format. Defaults per command:
@@ -8163,19 +8374,22 @@ EXAMPLES
   # CI smoke test
   tutuca ./src/components.js doctor
 `;
-async function run(argv) {
+async function run2(argv) {
   const target = argv?.[0];
   if (!target) {
     process.stdout.write(OVERVIEW);
     return;
   }
   if (target === "help") {
-    process.stdout.write(`help: ${describe}
+    process.stdout.write(`help: ${describe2}
 `);
     return;
   }
   const { COMMANDS: COMMANDS2 } = await Promise.resolve().then(() => (init__registry(), exports__registry));
-  const cmd = COMMANDS2[target];
+  const noModule = {
+    "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}
 `);
@@ -8187,8 +8401,11 @@ async function run(argv) {
   process.stdout.write("Run `tutuca help` for the full reference including signatures and flags.\n");
 }
 
+// tools/tutuca.js
+init_install_skill();
+
 // tools/cli/with-module.js
-import { parseArgs } from "node:util";
+import { parseArgs as parseArgs2 } from "node:util";
 
 // tools/cli/env.js
 init_anode();
@@ -8218,16 +8435,16 @@ async function createNodeEnv() {
 }
 
 // tools/cli/load.js
-import { resolve } from "node:path";
+import { resolve as resolve2 } from "node:path";
 async function loadAndNormalize(modulePath) {
-  const abs = resolve(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";
+import { writeFileSync as writeFileSync2 } from "node:fs";
 
 // tools/format/cli.js
 var exports_cli = {};
@@ -8619,7 +8836,7 @@ async function formatResult(formatName, result, options = {}) {
 async function emit(result, { format: format5, pretty, output }) {
   const text = await formatResult(format5, result, { pretty });
   if (output) {
-    writeFileSync(output, text);
+    writeFileSync2(output, text);
   } else {
     process.stdout.write(text);
     if (!text.endsWith(`
@@ -8631,7 +8848,7 @@ async function emit(result, { format: format5, pretty, output }) {
 
 // tools/cli/with-module.js
 async function runCommand(cmd, argv, globalOpts) {
-  const parsed = parseArgs({
+  const parsed = parseArgs2({
     args: argv,
     options: cmd.parseOptions ?? {},
     allowPositionals: true
@@ -8652,6 +8869,10 @@ async function runCommand(cmd, argv, globalOpts) {
 }
 
 // tools/tutuca.js
+var NO_MODULE_COMMANDS = {
+  help: exports_help,
+  "install-skill": exports_install_skill
+};
 function usageError(msg) {
   process.stderr.write(`tutuca: ${msg}
 Run \`tutuca help\` for usage.
@@ -8688,13 +8909,13 @@ function extractGlobals(argv) {
 async function main() {
   const { opts, rest } = extractGlobals(process.argv.slice(2));
   if (rest.length === 0 || opts.help && rest.length === 0) {
-    await run([], opts);
+    await run2([], opts);
     return;
   }
   let command;
   let commandArgs;
-  if (rest[0] === "help") {
-    command = "help";
+  if (NO_MODULE_COMMANDS[rest[0]]) {
+    command = rest[0];
     commandArgs = rest.slice(1);
   } else if (opts.module) {
     command = rest[0];
@@ -8706,12 +8927,13 @@ async function main() {
     command = rest[1];
     commandArgs = rest.slice(2);
   }
-  if (opts.help) {
-    await run([command], opts);
+  if (NO_MODULE_COMMANDS[command]) {
+    const args = opts.help ? [...commandArgs, "--help"] : commandArgs;
+    await NO_MODULE_COMMANDS[command].run(args, opts);
     return;
   }
-  if (command === "help") {
-    await run(commandArgs, opts);
+  if (opts.help) {
+    await run2([command], opts);
     return;
   }
   const cmd = COMMANDS[command];