wp-typia 0.24.5 → 0.24.7

package/README.md

@@ -49,7 +49,7 @@ Configuration files:
 Compatibility notes:
 
 - `@wp-typia/project-tools` is the canonical programmatic project orchestration package
-- the published CLI ships a built `dist` runtime, and the canonical Node bin supports `create`, `add`, `migrate`, `doctor`, `sync`, `skills`, `completions`, `mcp`, `--version`, `--help`, and template inspection without requiring a locally installed Bun binary
+- the published CLI ships a built `dist` runtime, and the canonical Node bin supports `create`, `add`, `migrate`, `doctor`, `sync`, `skills`, `complete`, the legacy `completions` alias, `mcp`, `--version`, `--help`, and template inspection without requiring a locally installed Bun binary
 - Bun remains supported for repository development, tests, and builds, while Node is the canonical npm runtime for the published CLI
 - when you request machine-readable output with `--format json`, CLI failures now include a stable `error.code` field so wrappers and CI can branch without parsing English text
 - the stable machine-handled branching key is `error.code`. Structured context like `error.command`, `error.kind`, and `error.tag` may also be useful to consumers, while free-form text like `error.message`, `error.summary`, and `error.detailLines` stays human-facing guidance and can evolve without notice
@@ -57,8 +57,8 @@ Compatibility notes:
 - internal runtime-bridge helper modules are implementation details; integrations
   should target the CLI or `@wp-typia/project-tools`, not CLI internals
 
-Maintainers: see [`docs/bunli-cli-migration.md`](https://imjlk.github.io/wp-typia/maintainers/bunli-cli-migration/)
-for historical Gunshi migration notes.
+Maintainers: see [`docs/gunshi-runtime-contract.md`](https://imjlk.github.io/wp-typia/maintainers/gunshi-runtime-contract/)
+for the Gunshi runtime contract.
 
 Project meta docs:
 

package/dist/cli.js

@@ -21,7 +21,7 @@ var package_default;
 var init_package = __esm(() => {
   package_default = {
     name: "wp-typia",
-    version: "0.24.5",
+    version: "0.24.7",
     description: "Canonical CLI package for wp-typia scaffolding and project workflows",
     packageManager: "bun@1.3.11",
     type: "module",
@@ -77,7 +77,7 @@ var init_package = __esm(() => {
     dependencies: {
       "@gunshi/plugin-completion": "0.32.0",
       "@wp-typia/api-client": "^0.4.6",
-      "@wp-typia/project-tools": "0.24.5",
+      "@wp-typia/project-tools": "0.24.6",
       gunshi: "0.32.0",
       zod: "4.3.6"
     },
@@ -1256,7 +1256,7 @@ function buildPatternCatalogDryRunSummaryLines(result, options) {
     ...normalizationNotes.map((note) => `  ${note}`)
   ];
 }
-var PATTERN_MISSING_NAME_MESSAGE = "`wp-typia add pattern` requires <name>. Usage: wp-typia add pattern <name>.", patternAddKindEntry;
+var PATTERN_MISSING_NAME_MESSAGE = "`wp-typia add pattern` requires <name>. Usage: wp-typia add pattern <name>.", LEGACY_TAG_FLAG_WARNING = "--tag is deprecated; use repeatable --tags instead.", patternAddKindEntry;
 var init_pattern = __esm(() => {
   init_add_kind_registry_shared();
   init_cli_string_flags();
@@ -1287,6 +1287,9 @@ var init_pattern = __esm(() => {
       const catalogTitle = rawCatalogTitle;
       const tags = normalizePatternTagFlags(context.flags.tags, context.flags.tag);
       const thumbnailUrl = rawThumbnailUrl;
+      if (context.flags.tag !== undefined && context.flags.format !== "json") {
+        context.warnLine(LEGACY_TAG_FLAG_WARNING);
+      }
       return {
         execute: (cwd) => context.addRuntime.runAddPatternCommand({
           catalogTitle,
@@ -1315,7 +1318,7 @@ var init_pattern = __esm(() => {
     },
     sortOrder: 60,
     supportsDryRun: true,
-    usage: "wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--tag <tag>...] [--thumbnail-url <url>] [--dry-run]",
+    usage: "wp-typia add pattern <name> [--scope <full|section>] [--section-role <role>] [--catalog-title <title>] [--tags <tag,...>] [--thumbnail-url <url>] [--dry-run]",
     visibleFieldNames: () => PATTERN_CATALOG_VISIBLE_FIELDS
   });
 });
@@ -1708,6 +1711,17 @@ function buildAddKindCompletionDetails(kind, options) {
 function supportsAddKindDryRun(kind) {
   return ADD_KIND_REGISTRY[kind].supportsDryRun;
 }
+function getAddKindOptions() {
+  return ADD_KIND_IDS2.map((kind) => ({
+    description: ADD_KIND_REGISTRY[kind].description,
+    name: kind,
+    value: kind
+  }));
+}
+function getAddNameLabel(kind) {
+  const resolvedKind = isAddKindId(kind) ? kind : "block";
+  return ADD_KIND_REGISTRY[resolvedKind].nameLabel;
+}
 var ADD_KIND_REGISTRY;
 var init_add_kind_registry = __esm(() => {
   init_add_kind_ids();
@@ -2233,9 +2247,6 @@ var init_runtime_bridge_sync = __esm(() => {
 function formatMissingAddKindDetailLine() {
   return `\`wp-typia add\` requires <kind>. Usage: wp-typia add ${formatAddKindUsagePlaceholder()} ...`;
 }
-function buildMissingAddKindDetailLines() {
-  return [formatMissingAddKindDetailLine()];
-}
 function shouldPrintMissingAddKindHelp(options) {
   if (typeof options.emitOutput === "boolean") {
     return options.emitOutput;
@@ -2484,6 +2495,9 @@ async function executePlannedAddKind(kind, executionContext, context) {
   const plan = await getAddKindExecutionPlan(kind, executionContext);
   return executePreparedAddKind(kind, context, plan);
 }
+function contextAllowsInteractivePrompts(flags) {
+  return flags.format !== "json";
+}
 async function executeAddCommand({
   cwd,
   emitOutput = true,
@@ -2501,36 +2515,53 @@ async function executeAddCommand({
   try {
     const addRuntime = await loadCliAddRuntime();
     const isInteractiveSession = interactive ?? isInteractiveTerminal();
-    if (!kind) {
+    const getOrCreatePrompt = async () => {
+      if (activePrompt) {
+        return activePrompt;
+      }
+      const { createReadlinePrompt } = await loadCliPromptRuntime();
+      activePrompt = prompt ?? createReadlinePrompt();
+      return activePrompt;
+    };
+    let resolvedKind = kind;
+    let resolvedName = name;
+    let promptedForKind = false;
+    if (!resolvedKind && isInteractiveSession && contextAllowsInteractivePrompts(flags)) {
+      const kindPrompt = await getOrCreatePrompt();
+      resolvedKind = await kindPrompt.select("Select what to add", getAddKindOptions().map((option) => ({
+        hint: option.description,
+        label: option.name,
+        value: option.value
+      })), 1);
+      promptedForKind = true;
+    }
+    if (!resolvedKind) {
       if (shouldPrintMissingAddKindHelp({ emitOutput })) {
         printLine(addRuntime.formatAddHelpText());
       }
       throw createCliDiagnosticCodeError12(CLI_DIAGNOSTIC_CODES16.MISSING_ARGUMENT, formatMissingAddKindDetailLine());
     }
-    if (!isAddKindId(kind)) {
-      throw createCliDiagnosticCodeError12(CLI_DIAGNOSTIC_CODES16.INVALID_COMMAND, `Unknown add kind "${kind}". Expected one of: ${formatAddKindList()}.`);
+    if (!isAddKindId(resolvedKind)) {
+      throw createCliDiagnosticCodeError12(CLI_DIAGNOSTIC_CODES16.INVALID_COMMAND, `Unknown add kind "${resolvedKind}". Expected one of: ${formatAddKindList()}.`);
+    }
+    if (!resolvedName && promptedForKind) {
+      const namePrompt = await getOrCreatePrompt();
+      resolvedName = await namePrompt.text(getAddNameLabel(resolvedKind), "", (value) => value.trim().length > 0 ? true : `${getAddNameLabel(resolvedKind)} is required.`);
     }
-    if (dryRun && !supportsAddKindDryRun(kind)) {
-      throw createCliDiagnosticCodeError12(CLI_DIAGNOSTIC_CODES16.INVALID_ARGUMENT, `\`wp-typia add ${kind}\` does not support \`--dry-run\` yet.`);
+    if (dryRun && !supportsAddKindDryRun(resolvedKind)) {
+      throw createCliDiagnosticCodeError12(CLI_DIAGNOSTIC_CODES16.INVALID_ARGUMENT, `\`wp-typia add ${resolvedKind}\` does not support \`--dry-run\` yet.`);
     }
     const executionContext = {
       addRuntime,
       cwd,
       flags,
-      getOrCreatePrompt: async () => {
-        if (activePrompt) {
-          return activePrompt;
-        }
-        const { createReadlinePrompt } = await loadCliPromptRuntime();
-        activePrompt = prompt ?? createReadlinePrompt();
-        return activePrompt;
-      },
+      getOrCreatePrompt,
       isInteractiveSession,
-      name,
+      name: resolvedName,
       positionalArgs,
       warnLine
     };
-    return await executePlannedAddKind(kind, executionContext, {
+    return await executePlannedAddKind(resolvedKind, executionContext, {
       cwd,
       dryRun,
       emitOutput,
@@ -2745,41 +2776,27 @@ var init_runtime_bridge = __esm(() => {
   init_runtime_bridge_sync();
 });
 
-// src/node-fallback/dispatchers/add.ts
+// src/portable-cli/dispatchers/add.ts
 var exports_add = {};
 __export(exports_add, {
-  dispatchNodeFallbackAdd: () => dispatchNodeFallbackAdd
+  dispatchPortableCliAdd: () => dispatchPortableCliAdd
 });
-import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES18,
-  createCliCommandError as createCliCommandError6
-} from "@wp-typia/project-tools/cli-diagnostics";
-function resolveNodeFallbackAddName(positionals) {
+import { createCliCommandError as createCliCommandError6 } from "@wp-typia/project-tools/cli-diagnostics";
+function resolvePortableCliAddName(positionals) {
   if (positionals[1] === "core-variation" && positionals[3]) {
     return positionals[3];
   }
   return positionals[2];
 }
-async function dispatchNodeFallbackAdd({
+async function dispatchPortableCliAdd({
   cwd,
   mergedFlags,
   positionals,
   printLine,
   warnLine
 }) {
-  if (!positionals[1]) {
-    if (shouldPrintMissingAddKindHelp({ format: mergedFlags.format })) {
-      const { formatAddHelpText } = await import("@wp-typia/project-tools/cli-add");
-      printLine(formatAddHelpText());
-    }
-    throw createCliCommandError6({
-      code: CLI_DIAGNOSTIC_CODES18.MISSING_ARGUMENT,
-      command: "add",
-      detailLines: buildMissingAddKindDetailLines()
-    });
-  }
   const kind = positionals[1];
-  const name = resolveNodeFallbackAddName(positionals);
+  const name = resolvePortableCliAddName(positionals);
   const positionalArgs = positionals.slice(1);
   if (mergedFlags.format === "json") {
     let completion;
@@ -2821,21 +2838,20 @@ async function dispatchNodeFallbackAdd({
   });
 }
 var init_add2 = __esm(() => {
-  init_cli_error_messages();
   init_runtime_bridge();
   init_runtime_bridge_output();
 });
 
-// src/node-fallback/dispatchers/create.ts
+// src/portable-cli/dispatchers/create.ts
 var exports_create = {};
 __export(exports_create, {
-  dispatchNodeFallbackCreate: () => dispatchNodeFallbackCreate
+  dispatchPortableCliCreate: () => dispatchPortableCliCreate
 });
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES19,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES18,
   createCliCommandError as createCliCommandError7
 } from "@wp-typia/project-tools/cli-diagnostics";
-async function dispatchNodeFallbackCreate({
+async function dispatchPortableCliCreate({
   cwd,
   mergedFlags,
   positionals,
@@ -2845,7 +2861,7 @@ async function dispatchNodeFallbackCreate({
   const projectDir = positionals[1];
   if (!projectDir) {
     throw createCliCommandError7({
-      code: CLI_DIAGNOSTIC_CODES19.MISSING_ARGUMENT,
+      code: CLI_DIAGNOSTIC_CODES18.MISSING_ARGUMENT,
       command: "create",
       detailLines: buildMissingCreateProjectDirDetailLines()
     });
@@ -2881,16 +2897,16 @@ var init_create2 = __esm(() => {
   init_cli_error_messages();
 });
 
-// src/node-fallback/doctor.ts
+// src/portable-cli/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
-  dispatchNodeFallbackDoctor: () => dispatchNodeFallbackDoctor
+  dispatchPortableCliDoctor: () => dispatchPortableCliDoctor
 });
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES20,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES19,
   createCliCommandError as createCliCommandError8
 } from "@wp-typia/project-tools/cli-diagnostics";
-async function renderNodeFallbackDoctorJson(cwd, exitPolicy, printLine) {
+async function renderPortableCliDoctorJson(cwd, exitPolicy, printLine) {
   const {
     createDoctorRunSummary,
     getDoctorChecks,
@@ -2904,21 +2920,21 @@ async function renderNodeFallbackDoctorJson(cwd, exitPolicy, printLine) {
   }, null, 2));
   if (summary.exitCode === 1) {
     throw createCliCommandError8({
-      code: CLI_DIAGNOSTIC_CODES20.DOCTOR_CHECK_FAILED,
+      code: CLI_DIAGNOSTIC_CODES19.DOCTOR_CHECK_FAILED,
       command: "doctor",
       detailLines: getDoctorExitFailureDetailLines(checks, { exitPolicy }),
       summary: "One or more doctor checks failed."
     });
   }
 }
-async function dispatchNodeFallbackDoctor({
+async function dispatchPortableCliDoctor({
   cwd,
   mergedFlags,
   printLine
 }) {
   const exitPolicy = mergedFlags["workspace-only"] ? "workspace-only" : "strict";
   if (mergedFlags.format === "json") {
-    await renderNodeFallbackDoctorJson(cwd, exitPolicy, printLine);
+    await renderPortableCliDoctorJson(cwd, exitPolicy, printLine);
     return;
   }
   await executeDoctorCommand(cwd, { exitPolicy });
@@ -2927,20 +2943,20 @@ var init_doctor = __esm(() => {
   init_runtime_bridge();
 });
 
-// src/node-fallback/templates.ts
+// src/portable-cli/templates.ts
 var exports_templates = {};
 __export(exports_templates, {
-  dispatchNodeFallbackTemplates: () => dispatchNodeFallbackTemplates
+  dispatchPortableCliTemplates: () => dispatchPortableCliTemplates
 });
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES21,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES20,
   createCliCommandError as createCliCommandError9
 } from "@wp-typia/project-tools/cli-diagnostics";
 import {
   getTemplateById,
   listTemplates
 } from "@wp-typia/project-tools/cli-templates";
-function renderNodeFallbackTemplatesJson(printLine, flags, subcommand) {
+function renderPortableCliTemplatesJson(printLine, flags, subcommand) {
   if (subcommand === "list") {
     printLine(JSON.stringify({
       templates: listTemplates()
@@ -2950,7 +2966,7 @@ function renderNodeFallbackTemplatesJson(printLine, flags, subcommand) {
   const templateId = flags.id;
   if (!templateId) {
     throw createCliCommandError9({
-      code: CLI_DIAGNOSTIC_CODES21.MISSING_ARGUMENT,
+      code: CLI_DIAGNOSTIC_CODES20.MISSING_ARGUMENT,
       command: "templates",
       detailLines: ["`wp-typia templates inspect` requires <template-id>."]
     });
@@ -2958,7 +2974,7 @@ function renderNodeFallbackTemplatesJson(printLine, flags, subcommand) {
   const template = getTemplateById(templateId);
   if (!template) {
     throw createCliCommandError9({
-      code: CLI_DIAGNOSTIC_CODES21.INVALID_ARGUMENT,
+      code: CLI_DIAGNOSTIC_CODES20.INVALID_ARGUMENT,
       command: "templates",
       detailLines: [`Unknown template "${templateId}".`]
     });
@@ -2967,7 +2983,7 @@ function renderNodeFallbackTemplatesJson(printLine, flags, subcommand) {
     template
   }, null, 2));
 }
-async function dispatchNodeFallbackTemplates({
+async function dispatchPortableCliTemplates({
   mergedFlags,
   positionals,
   printLine
@@ -2977,7 +2993,7 @@ async function dispatchNodeFallbackTemplates({
   const resolvedSubcommand = subcommand ?? (templateId ? "inspect" : "list");
   if (resolvedSubcommand !== "list" && resolvedSubcommand !== "inspect") {
     throw createCliCommandError9({
-      code: CLI_DIAGNOSTIC_CODES21.INVALID_COMMAND,
+      code: CLI_DIAGNOSTIC_CODES20.INVALID_COMMAND,
       command: "templates",
       detailLines: [
         `Unknown templates subcommand "${resolvedSubcommand}". Expected list or inspect.`
@@ -2985,7 +3001,7 @@ async function dispatchNodeFallbackTemplates({
     });
   }
   if (mergedFlags.format === "json") {
-    renderNodeFallbackTemplatesJson(printLine, {
+    renderPortableCliTemplatesJson(printLine, {
       format: mergedFlags.format,
       id: templateId
     }, resolvedSubcommand);
@@ -3020,21 +3036,21 @@ var WP_TYPIA_COMMAND_REGISTRY = [
     commandTree: true,
     description: "Scaffold a new wp-typia project.",
     name: "create",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["create"]
   },
   {
     commandTree: true,
     description: "Preview or apply the minimum retrofit plan for an existing project.",
     name: "init",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["init"]
   },
   {
     commandTree: true,
     description: "Run the common generated-project sync workflow.",
     name: "sync",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["sync"],
     subcommands: ["ai"]
   },
@@ -3042,7 +3058,7 @@ var WP_TYPIA_COMMAND_REGISTRY = [
     commandTree: true,
     description: "Extend an official wp-typia workspace.",
     name: "add",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["add"],
     subcommands: ADD_KIND_IDS2
   },
@@ -3050,7 +3066,7 @@ var WP_TYPIA_COMMAND_REGISTRY = [
     commandTree: true,
     description: "Run migration workflows.",
     name: "migrate",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["migrate"],
     subcommands: [
       "init",
@@ -3069,7 +3085,7 @@ var WP_TYPIA_COMMAND_REGISTRY = [
     commandTree: true,
     description: "Inspect scaffold templates.",
     name: "templates",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["templates"],
     subcommands: ["list", "inspect"]
   },
@@ -3077,51 +3093,51 @@ var WP_TYPIA_COMMAND_REGISTRY = [
     commandTree: true,
     description: "Run repository and project diagnostics.",
     name: "doctor",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["doctor"]
   },
   {
     commandTree: true,
     description: "Inspect or sync schema-driven MCP metadata.",
     name: "mcp",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["mcp"],
     subcommands: ["list", "sync"]
   },
   {
     commandTree: false,
     name: "help",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: []
   },
   {
     commandTree: false,
     name: "version",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: []
   },
   {
     commandTree: false,
     name: "skills",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: ["skills"],
     subcommands: ["list", "sync"]
   },
   {
     commandTree: false,
     name: "completions",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: []
   },
   {
     commandTree: false,
     name: "complete",
-    nodeFallback: true,
+    portableCli: true,
     optionGroups: []
   }
 ];
 var WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES = WP_TYPIA_COMMAND_REGISTRY.map((command) => command.name);
-var WP_TYPIA_NODE_FALLBACK_TOP_LEVEL_COMMAND_NAMES = WP_TYPIA_COMMAND_REGISTRY.filter((command) => command.nodeFallback).map((command) => command.name);
+var WP_TYPIA_PORTABLE_CLI_TOP_LEVEL_COMMAND_NAMES = WP_TYPIA_COMMAND_REGISTRY.filter((command) => command.portableCli).map((command) => command.name);
 var WP_TYPIA_TOP_LEVEL_COMMAND_NAMES = WP_TYPIA_COMMAND_REGISTRY.filter((command) => command.commandTree).map((command) => command.name);
 var WP_TYPIA_FUTURE_COMMAND_TREE = WP_TYPIA_COMMAND_REGISTRY.filter((command) => command.commandTree).map((command) => ({
   description: command.description,
@@ -3134,7 +3150,7 @@ for (const command of WP_TYPIA_COMMAND_REGISTRY) {
 }
 var WP_TYPIA_COMMAND_OPTION_GROUP_NAMES_BY_TOP_LEVEL_COMMAND = commandOptionGroupNamesByTopLevelCommand;
 
-// src/node-fallback/errors.ts
+// src/portable-cli/errors.ts
 import {
   CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES4,
   createCliCommandError as createCliCommandError3,
@@ -3245,7 +3261,6 @@ function findFirstPositional(argv, metadata) {
 }
 
 // src/command-option-metadata.ts
-import { z } from "zod";
 import {
   CLI_DIAGNOSTIC_CODES,
   createCliDiagnosticCodeError
@@ -3271,6 +3286,7 @@ var ADD_OPTION_METADATA = {
   },
   block: {
     description: "Target block slug/name for variation, core-variation, style, and end-to-end binding-source workflows.",
+    short: "b",
     type: "string"
   },
   "catalog-title": {
@@ -3292,6 +3308,7 @@ var ADD_OPTION_METADATA = {
   "dry-run": {
     argumentKind: "flag",
     description: "Preview workspace file updates and completion guidance without writing them.",
+    short: "d",
     type: "boolean"
   },
   "external-layer-id": {
@@ -3342,6 +3359,7 @@ var ADD_OPTION_METADATA = {
   },
   namespace: {
     description: "REST namespace for rest-resource and ai-feature workflows.",
+    short: "n",
     type: "string"
   },
   "permission-callback": {
@@ -3426,7 +3444,8 @@ var ADD_OPTION_METADATA = {
     type: "string"
   },
   template: {
-    description: "Optional built-in block family for the new block; interactive flows let you choose it when omitted and non-interactive runs default to basic.",
+    description: "Built-in block family for add block; one of basic, interactivity, persistence, or compound. Defaults to basic in non-interactive runs; interactive runs prompt when omitted.",
+    short: "t",
     type: "string"
   },
   "thumbnail-url": {
@@ -3434,12 +3453,13 @@ var ADD_OPTION_METADATA = {
     type: "string"
   },
   tags: {
-    description: "Comma-separated tags for typed pattern catalog entries; combine with repeatable --tag for single tags.",
+    description: "Comma-separated tags for typed pattern catalog entries.",
     repeatable: true,
     type: "string"
   },
   tag: {
-    description: "Repeatable single tag for typed pattern catalog entries; use --tags for comma-separated lists.",
+    description: "Legacy repeatable single-tag alias for typed pattern catalog entries; prefer --tags.",
+    hidden: true,
     repeatable: true,
     type: "string"
   },
@@ -3707,10 +3727,11 @@ var ALL_COMMAND_OPTION_METADATA = collectCommandOptionMetadata(...COMMAND_OPTION
 function collectOptionNamesByType(metadata, type) {
   return Object.entries(metadata).filter(([, option]) => option.type === type).map(([name]) => name);
 }
-function formatNodeFallbackOptionHelp(metadata) {
-  return Object.entries(metadata).map(([name, option]) => {
-    const short = option.short ? `, -${option.short}` : "";
-    return `- --${name}${short}: ${option.description}`;
+function formatPortableCliOptionHelp(metadata) {
+  return Object.entries(metadata).filter(([, option]) => !option.hidden).map(([name, option]) => {
+    const valueLabel = option.type === "string" ? " <value>" : "";
+    const short = option.short ? `, -${option.short}${valueLabel}` : "";
+    return `- --${name}${valueLabel}${short}: ${option.description}`;
   });
 }
 function buildCommandOptionParser(...metadataMaps) {
@@ -3752,6 +3773,9 @@ function createMissingOptionValueError(optionLabel) {
 function createUnknownOptionError(optionLabel) {
   return createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Unknown option \`${optionLabel}\`.`);
 }
+function createValueShortFlagClusterError(clusterLabel, optionLabel) {
+  return createCliDiagnosticCodeError(CLI_DIAGNOSTIC_CODES.INVALID_ARGUMENT, `Short flag cluster \`${clusterLabel}\` contains value-taking short flag \`${optionLabel}\`; spell value flags separately.`);
+}
 function walkArgvOptions(argv, options) {
   const flags = {};
   const nextArgv = [];
@@ -3769,6 +3793,23 @@ function walkArgvOptions(argv, options) {
       nextArgv.push(...argv.slice(index + (options.strict ? 1 : 0)));
       break;
     }
+    if (arg.length > 2 && arg.startsWith("-") && !arg.startsWith("--")) {
+      if (!options.strict) {
+        nextArgv.push(arg);
+        continue;
+      }
+      for (const shortName of arg.slice(1)) {
+        const shortFlag = options.parser.shortFlagMap.get(shortName);
+        if (!shortFlag) {
+          throw createUnknownOptionError(`-${shortName}`);
+        }
+        if (shortFlag.type !== "boolean") {
+          throw createValueShortFlagClusterError(arg, `-${shortName}`);
+        }
+        flags[shortFlag.name] = true;
+      }
+      continue;
+    }
     if (arg.length === 2 && arg.startsWith("-")) {
       const shortFlag = options.parser.shortFlagMap.get(arg.slice(1));
       if (!shortFlag || !options.strict && !optionNames.has(shortFlag.name)) {
@@ -4066,6 +4107,59 @@ function hasUnknownOptionBefore(argv, endIndex) {
   }
   return false;
 }
+function getEditDistance(left, right) {
+  const previous = Array.from({ length: right.length + 1 }, (_, index) => index);
+  const current = new Array(right.length + 1);
+  for (let leftIndex = 0;leftIndex < left.length; leftIndex += 1) {
+    current[0] = leftIndex + 1;
+    for (let rightIndex = 0;rightIndex < right.length; rightIndex += 1) {
+      const substitutionCost = left[leftIndex] === right[rightIndex] ? 0 : 1;
+      current[rightIndex + 1] = Math.min(current[rightIndex] + 1, previous[rightIndex + 1] + 1, previous[rightIndex] + substitutionCost);
+    }
+    for (let index = 0;index < current.length; index += 1) {
+      previous[index] = current[index];
+    }
+  }
+  return previous[right.length];
+}
+function isEdgeInsertionOrDeletionTypo(left, right) {
+  if (Math.abs(left.length - right.length) !== 1) {
+    return false;
+  }
+  const [shorter, longer] = left.length < right.length ? [left, right] : [right, left];
+  return longer.startsWith(shorter) || longer.endsWith(shorter);
+}
+function suggestTopLevelCommandTypo(value) {
+  const normalizedValue = value.trim().toLowerCase();
+  if (normalizedValue.length < 4) {
+    return null;
+  }
+  let bestCandidate = null;
+  for (const command of WP_TYPIA_RESERVED_TOP_LEVEL_COMMAND_NAMES) {
+    const normalizedCommand = command.toLowerCase();
+    const distance = getEditDistance(normalizedValue, normalizedCommand);
+    if (distance > 2) {
+      continue;
+    }
+    if (distance === 1 && isEdgeInsertionOrDeletionTypo(normalizedValue, normalizedCommand)) {
+      continue;
+    }
+    if (distance > 1 && normalizedValue[0] !== normalizedCommand[0]) {
+      continue;
+    }
+    if (bestCandidate === null || distance < bestCandidate.distance) {
+      bestCandidate = { command, distance };
+    }
+  }
+  return bestCandidate?.command ?? null;
+}
+function assertNoLikelyTopLevelCommandTypo(value) {
+  const suggestion = suggestTopLevelCommandTypo(value);
+  if (!suggestion) {
+    return;
+  }
+  throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.INVALID_ARGUMENT, `Unknown top-level command "${value}". Did you mean "${suggestion}"? If you meant to create a project named "${value}", run \`${WP_TYPIA_CANONICAL_CREATE_USAGE.replace("<project-dir>", value)}\`.`);
+}
 function resolveCanonicalCommandContext(argv) {
   const positionalIndexes = collectPositionalIndexes(argv, COMMAND_ROUTING_METADATA);
   const firstPositionalIndex = positionalIndexes[0] ?? -1;
@@ -4082,6 +4176,9 @@ function resolveCanonicalCommandContext(argv) {
   if (isReservedTopLevelCommandName(firstPositional)) {
     return firstPositional;
   }
+  if (suggestTopLevelCommandTypo(firstPositional)) {
+    return firstPositional;
+  }
   return positionalIndexes.length === 1 ? "create" : firstPositional;
 }
 function assertStringOptionValues(argv) {
@@ -4172,6 +4269,7 @@ function normalizeWpTypiaArgv(argv) {
     throw createCliDiagnosticCodeError2(CLI_DIAGNOSTIC_CODES3.INVALID_ARGUMENT, `The positional alias only accepts a single project directory. Use \`${WP_TYPIA_CANONICAL_CREATE_USAGE}\` for scaffold invocations with additional positional arguments, or check the command spelling if you meant another top-level command. Extra positional arguments: ${extraPositionals.map((value) => `\`${value}\``).join(", ")}.`);
   }
   assertPositionalAliasProjectDir(firstPositional);
+  assertNoLikelyTopLevelCommandTypo(firstPositional);
   const normalizedArgv = [
     ...argv.slice(0, firstPositionalIndex),
     "create",
@@ -4181,25 +4279,25 @@ function normalizeWpTypiaArgv(argv) {
   return normalizedArgv;
 }
 
-// src/node-fallback/help.ts
+// src/portable-cli/help.ts
 init_package();
 init_add_kind_ids();
 var STANDALONE_GUIDANCE_LINE = "Standalone wp-typia binaries are available from the GitHub release assets.";
-var NODE_FALLBACK_RUNTIME_SUMMARY_LINES = [
+var PORTABLE_CLI_RUNTIME_SUMMARY_LINES = [
   "Runtime: Node-first wp-typia CLI",
   "Gunshi provides the `complete` integration; the command registry owns shared dispatch and diagnostics.",
   "Supported command surfaces include create/init/add/migrate flows, doctor, sync, templates, MCP metadata, skills, completions, --help, and --version.",
   STANDALONE_GUIDANCE_LINE,
   "Output markers: WP_TYPIA_ASCII=1 forces ASCII markers, WP_TYPIA_ASCII=0 opts back into Unicode markers, and non-empty NO_COLOR requests ASCII markers when WP_TYPIA_ASCII is unset."
 ];
-var NODE_FALLBACK_NO_COMMAND_REASON_LINE = "No command provided. Run wp-typia --help for usage information.";
+var PORTABLE_CLI_NO_COMMAND_REASON_LINE = "No command provided. Run wp-typia --help for usage information.";
 function renderGeneralHelp(printLine) {
   printBlock(printLine, [
     `wp-typia ${package_default.version}`,
     "",
     "Canonical CLI package for wp-typia scaffolding and project workflows.",
     "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
+    ...PORTABLE_CLI_RUNTIME_SUMMARY_LINES,
     "",
     "Commands:",
     ...WP_TYPIA_FUTURE_COMMAND_TREE.map((command) => `- ${command.name}: ${command.description}`),
@@ -4212,21 +4310,28 @@ function renderGeneralHelp(printLine) {
   ]);
 }
 function renderNoCommandHelp(printLine) {
-  printBlock(printLine, [NODE_FALLBACK_NO_COMMAND_REASON_LINE, ""]);
+  printBlock(printLine, [PORTABLE_CLI_NO_COMMAND_REASON_LINE, ""]);
   renderGeneralHelp(printLine);
 }
-function renderNodeFallbackCommandHelp(printLine, config) {
+function renderUnknownHelpTarget(printLine, target) {
+  printBlock(printLine, [
+    `Unknown help target "${target}".`,
+    `Supported commands: ${WP_TYPIA_PORTABLE_CLI_TOP_LEVEL_COMMAND_NAMES.join(", ")}.`,
+    "Run wp-typia --help for general usage."
+  ]);
+}
+function renderPortableCliCommandHelp(printLine, config) {
   printBlock(printLine, [
     config.heading,
     "",
-    ...NODE_FALLBACK_RUNTIME_SUMMARY_LINES,
+    ...PORTABLE_CLI_RUNTIME_SUMMARY_LINES,
     "",
     ...config.bodyLines ? [...config.bodyLines, ""] : [],
     "Supported flags:",
-    ...formatNodeFallbackOptionHelp(config.optionMetadata)
+    ...formatPortableCliOptionHelp(config.optionMetadata)
   ]);
 }
-var NODE_FALLBACK_COMMAND_HELP_CONFIG = {
+var PORTABLE_CLI_COMMAND_HELP_CONFIG = {
   add: {
     bodyLines: [`Supported kinds: ${formatAddKindList()}`],
     heading: "Usage: wp-typia add <kind> <name>",
@@ -4263,7 +4368,8 @@ var NODE_FALLBACK_COMMAND_HELP_CONFIG = {
   },
   skills: {
     bodyLines: [
-      "List detected coding agents or generate a compact wp-typia SKILL.md from command metadata."
+      "List detected coding agents or generate a compact wp-typia SKILL.md from command metadata.",
+      "Use --local to install project-local skills; generated universal skills under .agents/skills/wp-typia/ are added to .gitignore."
     ],
     heading: "Usage: wp-typia skills <list|sync>",
     optionMetadata: SKILLS_OPTION_METADATA
@@ -4287,24 +4393,24 @@ var NODE_FALLBACK_COMMAND_HELP_CONFIG = {
     optionMetadata: {}
   }
 };
-var NODE_FALLBACK_HELP_RENDERERS = Object.fromEntries(Object.entries(NODE_FALLBACK_COMMAND_HELP_CONFIG).map(([command, config]) => [
+var PORTABLE_CLI_HELP_RENDERERS = Object.fromEntries(Object.entries(PORTABLE_CLI_COMMAND_HELP_CONFIG).map(([command, config]) => [
   command,
-  (printLine) => renderNodeFallbackCommandHelp(printLine, config)
+  (printLine) => renderPortableCliCommandHelp(printLine, config)
 ]));
 
-// src/node-fallback/errors.ts
-function createNodeFallbackNoCommandCliError() {
+// src/portable-cli/errors.ts
+function createPortableCliNoCommandCliError() {
   return createCliCommandError3({
     code: CLI_DIAGNOSTIC_CODES4.INVALID_COMMAND,
     command: "wp-typia",
-    detailLines: [NODE_FALLBACK_NO_COMMAND_REASON_LINE],
+    detailLines: [PORTABLE_CLI_NO_COMMAND_REASON_LINE],
     summary: "No command was provided."
   });
 }
-function isNodeFallbackNoCommandCliDiagnostic(error) {
-  return isCliDiagnosticError(error) && error.code === CLI_DIAGNOSTIC_CODES4.INVALID_COMMAND && error.command === "wp-typia" && error.detailLines.includes(NODE_FALLBACK_NO_COMMAND_REASON_LINE);
+function isPortableCliNoCommandCliDiagnostic(error) {
+  return isCliDiagnosticError(error) && error.code === CLI_DIAGNOSTIC_CODES4.INVALID_COMMAND && error.command === "wp-typia" && error.detailLines.includes(PORTABLE_CLI_NO_COMMAND_REASON_LINE);
 }
-function throwUnsupportedNodeFallbackCommand(command) {
+function throwUnsupportedPortableCliCommand(command) {
   throw createCliCommandError3({
     code: CLI_DIAGNOSTIC_CODES4.UNSUPPORTED_COMMAND,
     command,
@@ -4318,7 +4424,7 @@ function throwUnsupportedNodeFallbackCommand(command) {
     summary: "Unsupported wp-typia command."
   });
 }
-async function handleNodeFallbackEntrypointError(error, argv) {
+async function handlePortableCliEntrypointError(error, argv) {
   if (prefersStructuredCliArgv(argv)) {
     const diagnostic = createCliCommandError3({
       command: resolveCanonicalCommandContext(argv),
@@ -4332,7 +4438,7 @@ async function handleNodeFallbackEntrypointError(error, argv) {
     process.exitCode = 1;
     return;
   }
-  if (isNodeFallbackNoCommandCliDiagnostic(error)) {
+  if (isPortableCliNoCommandCliDiagnostic(error)) {
     process.exitCode = 1;
     return;
   }
@@ -4342,7 +4448,7 @@ async function handleNodeFallbackEntrypointError(error, argv) {
 
 // src/node-cli.ts
 import {
-  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES22,
+  CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES21,
   createCliCommandError as createCliCommandError10
 } from "@wp-typia/project-tools/cli-diagnostics";
 
@@ -4460,63 +4566,63 @@ import {
   CLI_DIAGNOSTIC_CODES as CLI_DIAGNOSTIC_CODES6,
   createCliDiagnosticCodeError as createCliDiagnosticCodeError3
 } from "@wp-typia/project-tools/cli-diagnostics";
-import { z as z2 } from "zod";
+import { z } from "zod";
 var WP_TYPIA_CONFIG_SOURCES = [
   "~/.config/wp-typia/config.json",
   ".wp-typiarc",
   ".wp-typiarc.json"
 ];
-var wordpressVersionSchema = z2.string().regex(/^\d+\.\d+(?:\.\d+)?$/u, 'expected dotted numeric WordPress version such as "6.7" or "6.7.1"');
-var wpTypiaSchemaSourceSchema = z2.object({
-  namespace: z2.string(),
-  path: z2.string()
+var wordpressVersionSchema = z.string().regex(/^\d+\.\d+(?:\.\d+)?$/u, 'expected dotted numeric WordPress version such as "6.7" or "6.7.1"');
+var wpTypiaSchemaSourceSchema = z.object({
+  namespace: z.string(),
+  path: z.string()
 }).strict();
-var wordpressCompatibilityConfigSchema = z2.object({
+var wordpressCompatibilityConfigSchema = z.object({
   minVersion: wordpressVersionSchema.optional(),
-  testedVersions: z2.array(wordpressVersionSchema).optional()
+  testedVersions: z.array(wordpressVersionSchema).optional()
 }).strict();
-var blockApiCompatibilityConfigSchema = z2.object({
-  allowUnknownFutureKeys: z2.boolean().optional(),
-  strict: z2.boolean().optional()
+var blockApiCompatibilityConfigSchema = z.object({
+  allowUnknownFutureKeys: z.boolean().optional(),
+  strict: z.boolean().optional()
 }).strict();
-var createConfigSchema = z2.object({
-  "alternate-render-targets": z2.string().optional(),
-  "inner-blocks-preset": z2.string().optional(),
-  "data-storage": z2.string().optional(),
-  "dry-run": z2.boolean().optional(),
-  "external-layer-id": z2.string().optional(),
-  "external-layer-source": z2.string().optional(),
-  namespace: z2.string().optional(),
-  "no-install": z2.boolean().optional(),
-  "package-manager": z2.string().optional(),
-  "persistence-policy": z2.string().optional(),
-  "php-prefix": z2.string().optional(),
-  profile: z2.string().optional(),
-  "query-post-type": z2.string().optional(),
-  template: z2.string().optional(),
-  "text-domain": z2.string().optional(),
-  variant: z2.string().optional(),
-  "with-migration-ui": z2.boolean().optional(),
-  "with-test-preset": z2.boolean().optional(),
-  "with-wp-env": z2.boolean().optional(),
-  yes: z2.boolean().optional()
+var createConfigSchema = z.object({
+  "alternate-render-targets": z.string().optional(),
+  "inner-blocks-preset": z.string().optional(),
+  "data-storage": z.string().optional(),
+  "dry-run": z.boolean().optional(),
+  "external-layer-id": z.string().optional(),
+  "external-layer-source": z.string().optional(),
+  namespace: z.string().optional(),
+  "no-install": z.boolean().optional(),
+  "package-manager": z.string().optional(),
+  "persistence-policy": z.string().optional(),
+  "php-prefix": z.string().optional(),
+  profile: z.string().optional(),
+  "query-post-type": z.string().optional(),
+  template: z.string().optional(),
+  "text-domain": z.string().optional(),
+  variant: z.string().optional(),
+  "with-migration-ui": z.boolean().optional(),
+  "with-test-preset": z.boolean().optional(),
+  "with-wp-env": z.boolean().optional(),
+  yes: z.boolean().optional()
 }).strict();
-var addBlockConfigSchema = z2.object({
-  "alternate-render-targets": z2.string().optional(),
-  "data-storage": z2.string().optional(),
-  "external-layer-id": z2.string().optional(),
-  "external-layer-source": z2.string().optional(),
-  "inner-blocks-preset": z2.string().optional(),
-  "persistence-policy": z2.string().optional(),
-  template: z2.string().optional()
+var addBlockConfigSchema = z.object({
+  "alternate-render-targets": z.string().optional(),
+  "data-storage": z.string().optional(),
+  "external-layer-id": z.string().optional(),
+  "external-layer-source": z.string().optional(),
+  "inner-blocks-preset": z.string().optional(),
+  "persistence-policy": z.string().optional(),
+  template: z.string().optional()
 }).strict();
-var addConfigSchema = z2.object({
+var addConfigSchema = z.object({
   block: addBlockConfigSchema.optional()
 }).strict();
-var mcpConfigSchema = z2.object({
-  schemaSources: z2.array(wpTypiaSchemaSourceSchema).optional()
+var mcpConfigSchema = z.object({
+  schemaSources: z.array(wpTypiaSchemaSourceSchema).optional()
 }).strict();
-var wpTypiaUserConfigSchema = z2.object({
+var wpTypiaUserConfigSchema = z.object({
   add: addConfigSchema.optional(),
   compatibility: blockApiCompatibilityConfigSchema.optional(),
   create: createConfigSchema.optional(),
@@ -5028,6 +5134,7 @@ var defaultSkillRuntime = {
   homeDir: () => os2.homedir()
 };
 var GENERATED_SKILL_MARKER = ".wp-typia-skill.json";
+var LOCAL_SKILL_GITIGNORE_ENTRY = ".agents/skills/wp-typia/";
 var SKILL_FILE = "SKILL.md";
 function configHome(home) {
   return process.env.XDG_CONFIG_HOME || path7.join(home, ".config");
@@ -5117,8 +5224,10 @@ function optionNamesForGroups(groupNames) {
   const options = new Set;
   for (const groupName of groupNames) {
     const metadata = COMMAND_OPTION_METADATA_BY_GROUP[groupName];
-    for (const optionName of Object.keys(metadata)) {
-      options.add(optionName);
+    for (const [optionName, option] of Object.entries(metadata)) {
+      if (!option.hidden) {
+        options.add(optionName);
+      }
     }
   }
   return [...options].sort();
@@ -5302,6 +5411,41 @@ function resolveParent(dir) {
     }
   }
 }
+function detectLineEnding(content) {
+  return content.includes(`\r
+`) ? `\r
+` : `
+`;
+}
+async function ensureLocalSkillsGitignore(cwd) {
+  const gitignorePath = path7.join(cwd, ".gitignore");
+  const entries = [LOCAL_SKILL_GITIGNORE_ENTRY];
+  let content = "";
+  let exists = true;
+  try {
+    content = await fsp.readFile(gitignorePath, "utf8");
+  } catch (error) {
+    if (error.code !== "ENOENT") {
+      throw error;
+    }
+    exists = false;
+  }
+  const lines = content.split(/\r?\n/u).map((line) => line.trim());
+  const missingEntries = entries.filter((entry) => !lines.includes(entry));
+  if (missingEntries.length === 0) {
+    return { entries, path: gitignorePath, updated: false };
+  }
+  const lineEnding = exists ? detectLineEnding(content) : `
+`;
+  let nextContent = content;
+  if (nextContent.length > 0 && !nextContent.endsWith(`
+`)) {
+    nextContent += lineEnding;
+  }
+  nextContent += missingEntries.map((entry) => `${entry}${lineEnding}`).join("");
+  await fsp.writeFile(gitignorePath, nextContent, "utf8");
+  return { entries, path: gitignorePath, updated: true };
+}
 async function syncSkills(options = {}) {
   const runtime = options.runtime ?? defaultSkillRuntime;
   const cwd = options.cwd ?? process.cwd();
@@ -5316,8 +5460,14 @@ async function syncSkills(options = {}) {
   const hash = createHash("sha256").update(content).digest("hex").slice(0, 16);
   const cacheKey = stalenessCacheKey(skillName, isGlobal, cwd, canonicalBase);
   const previousState = readState(cacheKey, runtime);
+  const gitignore = isGlobal ? undefined : await ensureLocalSkillsGitignore(cwd);
   if (!options.force && previousState?.hash === hash && previousState.agentKey === agentKey && skillTargetsAreCurrent(canonicalDir, agentDirs, content)) {
-    return { agents: [], paths: [], updated: false };
+    return {
+      agents: [],
+      gitignore,
+      paths: [],
+      updated: Boolean(gitignore?.updated)
+    };
   }
   await fsp.mkdir(canonicalDir, { recursive: true });
   await fsp.writeFile(path7.join(canonicalDir, SKILL_FILE), content, "utf8");
@@ -5352,14 +5502,15 @@ async function syncSkills(options = {}) {
   writeState(cacheKey, { agentKey, hash }, runtime);
   return {
     agents: installs,
+    gitignore,
     paths: [canonicalDir],
     updated: true
   };
 }
 
-// src/node-fallback/version.ts
+// src/portable-cli/version.ts
 init_package();
-function renderNodeFallbackVersion(printLine, options = {}) {
+function renderPortableCliVersion(printLine, options = {}) {
   if (options.format === "json") {
     printLine(JSON.stringify({
       ok: true,
@@ -5375,8 +5526,8 @@ function renderNodeFallbackVersion(printLine, options = {}) {
 }
 
 // src/node-cli.ts
-var NODE_FALLBACK_OPTION_PARSER = buildCommandOptionParser(ALL_COMMAND_OPTION_METADATA);
-var NODE_FALLBACK_BOOLEAN_OPTION_NAMES = ["help", "version"];
+var PORTABLE_CLI_OPTION_PARSER = buildCommandOptionParser(ALL_COMMAND_OPTION_METADATA);
+var PORTABLE_CLI_BOOLEAN_OPTION_NAMES = ["help", "version"];
 var printLine = (line) => {
   console.log(line);
 };
@@ -5397,7 +5548,7 @@ function hasFlagBeforeTerminator(argv, flag) {
 function parseGlobalFlags(argv) {
   const { argv: nextArgv, flags } = extractKnownOptionValuesFromArgv(argv, {
     optionNames: ["format", "id"],
-    parser: NODE_FALLBACK_OPTION_PARSER
+    parser: PORTABLE_CLI_OPTION_PARSER
   });
   return {
     argv: nextArgv,
@@ -5407,7 +5558,7 @@ function parseGlobalFlags(argv) {
     }
   };
 }
-async function applyNodeFallbackConfigDefaults(command, subcommand, flags, config) {
+async function applyPortableCliConfigDefaults(command, subcommand, flags, config) {
   if (command === "create") {
     return {
       ...flags,
@@ -5441,34 +5592,34 @@ function commandNeedsNodeCliConfig(command, subcommand) {
 }
 function parseArgv(argv) {
   return parseCommandArgvWithMetadata(argv, {
-    extraBooleanOptionNames: NODE_FALLBACK_BOOLEAN_OPTION_NAMES,
-    parser: NODE_FALLBACK_OPTION_PARSER
+    extraBooleanOptionNames: PORTABLE_CLI_BOOLEAN_OPTION_NAMES,
+    parser: PORTABLE_CLI_OPTION_PARSER
   });
 }
-async function dispatchNodeFallbackCompletion({
+async function dispatchPortableCliCompletion({
   positionals,
   printLine: printLine2
 }) {
   const shell = positionals[1];
   printLine2(renderCompletionScript(shell));
 }
-var dispatchNodeFallbackAddLazy = async (context) => {
-  const { dispatchNodeFallbackAdd: dispatchNodeFallbackAdd2 } = await Promise.resolve().then(() => (init_add2(), exports_add));
-  await dispatchNodeFallbackAdd2(context);
+var dispatchPortableCliAddLazy = async (context) => {
+  const { dispatchPortableCliAdd: dispatchPortableCliAdd2 } = await Promise.resolve().then(() => (init_add2(), exports_add));
+  await dispatchPortableCliAdd2(context);
 };
-var dispatchNodeFallbackCreateLazy = async (context) => {
-  const { dispatchNodeFallbackCreate: dispatchNodeFallbackCreate2 } = await Promise.resolve().then(() => (init_create2(), exports_create));
-  await dispatchNodeFallbackCreate2(context);
+var dispatchPortableCliCreateLazy = async (context) => {
+  const { dispatchPortableCliCreate: dispatchPortableCliCreate2 } = await Promise.resolve().then(() => (init_create2(), exports_create));
+  await dispatchPortableCliCreate2(context);
 };
-var dispatchNodeFallbackDoctorLazy = async (context) => {
-  const { dispatchNodeFallbackDoctor: dispatchNodeFallbackDoctor2 } = await Promise.resolve().then(() => (init_doctor(), exports_doctor));
-  await dispatchNodeFallbackDoctor2(context);
+var dispatchPortableCliDoctorLazy = async (context) => {
+  const { dispatchPortableCliDoctor: dispatchPortableCliDoctor2 } = await Promise.resolve().then(() => (init_doctor(), exports_doctor));
+  await dispatchPortableCliDoctor2(context);
 };
-var dispatchNodeFallbackTemplatesLazy = async (context) => {
-  const { dispatchNodeFallbackTemplates: dispatchNodeFallbackTemplates2 } = await Promise.resolve().then(() => (init_templates(), exports_templates));
-  await dispatchNodeFallbackTemplates2(context);
+var dispatchPortableCliTemplatesLazy = async (context) => {
+  const { dispatchPortableCliTemplates: dispatchPortableCliTemplates2 } = await Promise.resolve().then(() => (init_templates(), exports_templates));
+  await dispatchPortableCliTemplates2(context);
 };
-async function dispatchNodeFallbackSkills({
+async function dispatchPortableCliSkills({
   cwd,
   mergedFlags,
   positionals,
@@ -5507,27 +5658,32 @@ async function dispatchNodeFallbackSkills({
       printLine2("Skills are up to date.");
       return;
     }
-    printLine2(`Synced skills to ${result.paths.length} location(s).`);
+    if (result.paths.length > 0) {
+      printLine2(`Synced skills to ${result.paths.length} location(s).`);
+    }
     for (const install of result.agents) {
       const reason = install.reason ? ` (${install.reason})` : "";
       printLine2(`  ${install.agent}: ${install.mode} -> ${install.path}${reason}`);
     }
+    if (result.gitignore?.updated) {
+      printLine2(`Updated .gitignore for generated local skills: ${result.gitignore.entries.join(", ")}`);
+    }
     return;
   }
   throw createCliCommandError10({
-    code: CLI_DIAGNOSTIC_CODES22.INVALID_COMMAND,
+    code: CLI_DIAGNOSTIC_CODES21.INVALID_COMMAND,
     command: "skills",
     detailLines: [
       `Unknown skills subcommand "${subcommand}". Expected list or sync.`
     ]
   });
 }
-var NODE_FALLBACK_COMMAND_DISPATCHERS = {
-  add: dispatchNodeFallbackAddLazy,
-  complete: dispatchNodeFallbackCompletion,
-  completions: dispatchNodeFallbackCompletion,
-  create: dispatchNodeFallbackCreateLazy,
-  doctor: dispatchNodeFallbackDoctorLazy,
+var PORTABLE_CLI_COMMAND_DISPATCHERS = {
+  add: dispatchPortableCliAddLazy,
+  complete: dispatchPortableCliCompletion,
+  completions: dispatchPortableCliCompletion,
+  create: dispatchPortableCliCreateLazy,
+  doctor: dispatchPortableCliDoctorLazy,
   init: async ({
     cwd,
     mergedFlags,
@@ -5619,8 +5775,8 @@ var NODE_FALLBACK_COMMAND_DISPATCHERS = {
       userConfig: config
     });
   },
-  skills: dispatchNodeFallbackSkills,
-  templates: dispatchNodeFallbackTemplatesLazy
+  skills: dispatchPortableCliSkills,
+  templates: dispatchPortableCliTemplatesLazy
 };
 async function runNodeCli(argv = process.argv.slice(2)) {
   const normalizedArgv = normalizeWpTypiaArgv(argv);
@@ -5640,7 +5796,7 @@ async function runNodeCli(argv = process.argv.slice(2)) {
   const helpTarget = command === "help" ? subcommand : command;
   const versionRequested = hasFlagBeforeTerminator(cliArgv, "--version") || command === "version";
   if (cliArgv.length === 0) {
-    const noCommandError = createNodeFallbackNoCommandCliError();
+    const noCommandError = createPortableCliNoCommandCliError();
     if (rawMergedFlags.format !== "json") {
       renderNoCommandHelp(printLine);
     }
@@ -5648,7 +5804,7 @@ async function runNodeCli(argv = process.argv.slice(2)) {
   }
   if (helpRequested) {
     if (helpTarget) {
-      const helpRenderer = NODE_FALLBACK_HELP_RENDERERS[helpTarget];
+      const helpRenderer = PORTABLE_CLI_HELP_RENDERERS[helpTarget];
       if (helpRenderer) {
         helpRenderer(printLine);
         return;
@@ -5661,20 +5817,20 @@ async function runNodeCli(argv = process.argv.slice(2)) {
       renderGeneralHelp(printLine);
       return;
     }
-    renderGeneralHelp(printLine);
+    renderUnknownHelpTarget(printLine, helpTarget);
     return;
   }
   if (versionRequested) {
-    renderNodeFallbackVersion(printLine, {
+    renderPortableCliVersion(printLine, {
       format: typeof rawMergedFlags.format === "string" ? rawMergedFlags.format : undefined
     });
     return;
   }
-  const commandDispatcher = command && NODE_FALLBACK_COMMAND_DISPATCHERS[command];
+  const commandDispatcher = command && PORTABLE_CLI_COMMAND_DISPATCHERS[command];
   if (commandDispatcher) {
     const configNeeded = commandNeedsNodeCliConfig(command, subcommand);
     const config = configNeeded ? await loadNodeCliConfig(process.cwd(), configOverridePath) : {};
-    const mergedFlags = configNeeded ? await applyNodeFallbackConfigDefaults(command, subcommand, rawMergedFlags, config) : rawMergedFlags;
+    const mergedFlags = configNeeded ? await applyPortableCliConfigDefaults(command, subcommand, rawMergedFlags, config) : rawMergedFlags;
     await commandDispatcher({
       config,
       cwd: process.cwd(),
@@ -5685,7 +5841,7 @@ async function runNodeCli(argv = process.argv.slice(2)) {
     });
     return;
   }
-  throwUnsupportedNodeFallbackCommand(command ?? "(missing)");
+  throwUnsupportedPortableCliCommand(command ?? "(missing)");
 }
 
 // src/gunshi-cli.ts
@@ -5720,7 +5876,11 @@ function hasFlagBeforeTerminator2(argv, flag) {
 }
 function shouldUseGunshiCompletion(argv, versions = process.versions) {
   const [command] = argv;
-  return typeof versions.bun !== "string" && command === "complete" && !hasFlagBeforeTerminator2(argv, "--help") && !hasFlagBeforeTerminator2(argv, "-h") && !hasFlagBeforeTerminator2(argv, "--version") && !hasFlagBeforeTerminator2(argv, "-v");
+  return typeof versions.bun !== "string" && (command === "complete" || command === "completions") && !hasFlagBeforeTerminator2(argv, "--help") && !hasFlagBeforeTerminator2(argv, "-h") && !hasFlagBeforeTerminator2(argv, "--version") && !hasFlagBeforeTerminator2(argv, "-v");
+}
+function normalizeGunshiCompletionArgv(argv) {
+  const [command, ...rest] = argv;
+  return command === "completions" ? ["complete", ...rest] : argv;
 }
 function completionEntries() {
   return WP_TYPIA_COMMAND_REGISTRY.map((command) => ({
@@ -5753,7 +5913,7 @@ async function runGunshiCli(argv = process.argv.slice(2)) {
     await runNodeCli(normalizeFallbackShortAliases(argv));
     return;
   }
-  await cli(argv, wpTypiaGunshiCommand, {
+  await cli(normalizeGunshiCompletionArgv(argv), wpTypiaGunshiCommand, {
     fallbackToEntry: true,
     name: "wp-typia",
     plugins: [
@@ -5773,7 +5933,7 @@ async function runGunshiCliEntrypoint(argv = process.argv.slice(2)) {
   try {
     await runGunshiCli(argv);
   } catch (error) {
-    await handleNodeFallbackEntrypointError(error, argv);
+    await handlePortableCliEntrypointError(error, argv);
   }
 }
 if (process.argv[1] && path9.resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
@@ -5785,4 +5945,4 @@ export {
   runGunshiCli
 };
 
-//# debugId=B1E7487EE82BF9AB64756E2164756E21
+//# debugId=23F1B8999F88E0E464756E2164756E21

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wp-typia",
-  "version": "0.24.5",
+  "version": "0.24.7",
   "description": "Canonical CLI package for wp-typia scaffolding and project workflows",
   "packageManager": "bun@1.3.11",
   "type": "module",
@@ -56,7 +56,7 @@
   "dependencies": {
     "@gunshi/plugin-completion": "0.32.0",
     "@wp-typia/api-client": "^0.4.6",
-    "@wp-typia/project-tools": "0.24.5",
+    "@wp-typia/project-tools": "0.24.6",
     "gunshi": "0.32.0",
     "zod": "4.3.6"
   },