@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/README.md

@@ -1,9 +1,9 @@
-# @wootsup/yt-builder-mcp. YT Builder MCP for YOOtheme Pro (unofficial)
+# @wootsup/yt-builder-mcp. MCP for YOOtheme Pro
 
 > Drive your page builder via MCP. Built for YOOtheme Pro 4.0+ on **WordPress** and **Joomla 5/6**. Connect **Claude Desktop**, **Claude Code**, **Cursor**, **Zed**, **Continue**, **Cline**, **Roo Code**, **Codex CLI**, or **Gemini CLI** in one command.
 
 > Independent third-party project. YOOtheme® is a registered trademark of YOOtheme GmbH
-> ([yootheme.com](https://yootheme.com)). YT Builder MCP is built by WootsUp (getimo
+> ([yootheme.com](https://yootheme.com)). MCP for YOOtheme Pro is built by WootsUp (getimo
 > productions) and is not affiliated with, endorsed by, or sponsored by YOOtheme.
 > The integration uses YOOtheme Pro's public extension points.
 
@@ -17,11 +17,11 @@
 # 1. Install the host plugin for your CMS.
 #    WordPress: yt-builder-mcp-*.zip plugin.
 #    Joomla 5/6: pkg_ytbmcp-*.zip package (three sub-extensions in one go).
-#    See https://github.com/wootsup/yt-builder-mcp/releases
+#    See https://wootsup.com/products/yt-builder/
 
 # 2. Generate a Bearer key.
-#    WordPress: wp-admin → Tools → "YT Builder MCP" → Bearer Keys.
-#    Joomla:    Administrator → Components → "YT Builder MCP" → Bearer Keys.
+#    WordPress: wp-admin → Tools → "MCP for YOOtheme Pro" → Bearer Keys.
+#    Joomla:    Administrator → Components → "MCP for YOOtheme Pro" → Bearer Keys.
 #    Key format: ytb_(live|test)_<payloadB64Url>.<sigB64Url>
 #    The key is shown ONCE. Copy it now; it cannot be recovered later.
 
@@ -63,29 +63,36 @@ The wizard auto-detects and configures the following clients:
 
 ## Tool surface (gateway model)
 
-The server catalogues **52 tools + 2 gateways = 54 reachable** end-to-end,
-of which **42 are advertised in `tools/list`** (well under Cursor's ~40-tool
-cap — the 3-lane split keeps the advertised surface small while every
-catalogued tool stays callable):
+The server catalogues **60 tools + 2 gateways = 62 reachable** end-to-end,
+of which **49 are advertised in `tools/list`** — fewer than are callable.
+That is what the 3-lane split buys: a shorter advertised list for clients
+that handle long tool lists poorly, while every catalogued tool stays
+reachable through a gateway:
 
 - **2 direct top-level tools** (always in `tools/list`):
   `yootheme_builder_health`, `yootheme_builder_diagnose`. The
   "the gateway itself might be broken" escape hatch.
-- **38 essential forwarded tools** (always in `tools/list`): the most-used
+- **45 essential forwarded tools** (always in `tools/list`): the most-used
   reads and writes (`pages_list`, `pages_create`, `pages_delete`,
-  `page_dynamize`, `get_etag`, `element_list`, `element_add`,
+  `pages_set_status`, `pages_restore` (the one correct way back from the
+  trash — a gateway-only placement would leave it discoverable only to a
+  caller who already knows it exists),
+  `page_generate_dynamic`, `get_etag`, `element_list`, `element_add`,
   `element_update_settings`, `sources_list`, `element_types_list`,
   `inspect_multi_items_binding`, the multi-site `sites_list` / `sites_test` /
-  `use_site`, and the bind→save→publish chain `element_bind_source` /
-  `page_save` / `page_publish`, among others).
-- **2 gateway tools** exposing the remaining **12 advanced tools**:
-  - `yootheme_builder_advanced` (write-capable) routes **all 12**
-    (`page_get_schema`, `element_unbind_source`,
-    `clean_implode_directives`, `inspect_sublayout`, `layout_query`,
+  `use_site`, `get_skill` (the full-guide retrieval tool), `modules_delete`
+  (the one gateway-only destructive tool that removes data outside the
+  layout tree, promoted so a host can gate it individually), and the
+  bind→save→publish→unbind chain `element_bind_source` / `page_save` /
+  `page_publish` / `element_unbind_source`, among others).
+- **2 gateway tools** exposing the remaining **13 advanced tools**:
+  - `yootheme_builder_advanced` (write-capable) routes **all 13**
+    (`clean_implode_directives`, `inspect_sublayout`, `layout_query`,
     `library_save_as`, `library_delete`, `local_content_types`,
-    `local_content_read`, `pages_audit`, `heading_outline`, `navigation`).
+    `local_content_read`, `pages_audit`, `heading_outline`, `navigation`,
+    `header_transparency_set`, `modules_update`, `modules_create`).
   - `yootheme_builder_advanced_read` (read-only-annotated) routes only the
-    **8 read-only** advanced tools (`page_get_schema`, `inspect_sublayout`,
+    **7 read-only** advanced tools (`inspect_sublayout`,
     `layout_query`, `local_content_types`, `local_content_read`,
     `pages_audit`, `heading_outline`, `navigation`), so MCP hosts can
     auto-allow pure inspection without a per-call write-approval prompt.
@@ -93,20 +100,13 @@ catalogued tool stays callable):
   (returns the schema) or `({ tool, arguments })` to execute.
 
 See `skills/yt-builder-mcp/SKILL.md` for the full catalog and canonical
-workflows, and `docs/TOOL-CATALOG.md` for an auto-generated reference.
-
-## Tool catalogue
-
-| Domain      | Count | Tools                                                                                                                                                                |
-|-------------|------:|---------------------------------------------------------------------------------------------------------------------------------------------------------------------|
-| Health      |     2 | `health`, `diagnose`                                                                                                                                                |
-| Sites       |     2 | `sites_list`, `sites_test`                                                                                                                                          |
-| Pages       |     7 | `pages_list`, `page_get_layout`, `page_get_schema`, `template_summary`, `get_etag`, `page_save`, `page_publish`                                                     |
-| Elements    |     7 | `element_list`, `element_get`, `element_add`, `element_update_settings`, `element_move`, `element_clone`, `element_delete`                                          |
-| Sources     |     5 | `sources_list`, `element_get_binding`, `element_bind_source`, `element_unbind_source`, `inspect_multi_items_binding`                                                |
-| Inspection  |     3 | `element_types_list`, `element_type_get_schema`, `clean_implode_directives`                                                                                         |
-| Sublayout   |     1 | `inspect_sublayout` (F154 — fragment subtree + render-time inner-grid gate; advanced/gateway-routed)                                                                |
-| Gateway     |     2 | `advanced` (write, routes all 10 advanced tools), `advanced_read` (read-only, routes the 6 read-only advanced tools)                                                  |
+workflows, and `docs/TOOL-CATALOG.md` for an auto-generated, per-tool
+reference (regenerated from the live registry by
+`node scripts/extract-tools.mjs` — never hand-copied here, which is
+exactly why the numbers above stay accurate release over release; an
+earlier, hand-maintained domain-count table on this exact spot had
+drifted to less than half the real tool count and a stale gateway
+count before it was replaced with this pointer).
 
 All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
 
@@ -114,7 +114,18 @@ All tool names are prefixed with `yootheme_builder_` at the MCP server boundary.
 
 ```
 yt-builder-mcp setup            Interactive first-run wizard (default).
+yt-builder-mcp doctor           Diagnose connectivity (Node version, corporate
+                                 proxy/TLS, site reachability, bearer validity,
+                                 update status). Run this first when setup "hangs".
 yt-builder-mcp install-skill    Install the bundled agent skill.
+yt-builder-mcp uninstall        Remove yt-builder-mcp from configured AI clients
+  (alias: remove)               (and, optionally, the installed skill).
+yt-builder-mcp add-site         Add a site to the multi-site registry (see
+                                 "Multi-site setup" below).
+yt-builder-mcp list-sites       List configured sites (no network calls).
+yt-builder-mcp remove-site <id> Remove a site; auto-promotes the next as default.
+yt-builder-mcp set-default <id> Flip which configured site is the default.
+yt-builder-mcp test-site <id>   Probe /health + /etag for one configured site.
 yt-builder-mcp --version, -v    Print package version.
 yt-builder-mcp --help, -h       Show usage.
 ```
@@ -131,9 +142,9 @@ AI clients that follow the `~/AGENTS.md` discovery protocol. The
 single location keeps the skill discoverable across every supported
 client without per-client write logic.
 
-The skill ships with the 5 canonical workflows (build hero, bind
-source, clone section, diagnose 401, add custom element) plus a
-26-tool auto-generated catalog appendix.
+The skill ships with the 6 canonical workflows (build hero, bind
+source, clone section, diagnose 401, add custom element, SEO audit)
+plus a 60-tool auto-generated catalog appendix.
 
 ## MCPB bundle (Claude Desktop one-click install)
 
@@ -160,10 +171,15 @@ When launched by an AI client (or directly):
 |----------|-----------|---------|
 | `YTB_MCP_SITE_URL` | Yes | Host CMS base URL (e.g. `https://example.com`). Works for BOTH WordPress and Joomla. Trailing slash is stripped. |
 | `YTB_MCP_WP_URL` | No (deprecated) | Legacy alias for `YTB_MCP_SITE_URL`. Still honoured for older WordPress-only configurations. A non-fatal deprecation notice is written to stderr when this is used without `YTB_MCP_SITE_URL`. |
-| `YTB_MCP_BEARER_TOKEN` | Yes | Bearer key from wp-admin (WordPress: Tools → "YT Builder MCP") or Administrator → Components → "YT Builder MCP" (Joomla). Format-checked client-side: must match `ytb_(live\|test)_<payload>.<sig>`. Do **not** prepend `Bearer `. The MCP server adds it. |
+| `YTB_MCP_BEARER_TOKEN` | Yes | Bearer key from wp-admin (WordPress: Tools → "MCP for YOOtheme Pro") or Administrator → Components → "MCP for YOOtheme Pro" (Joomla). Format-checked client-side: must match `ytb_(live\|test)_<payload>.<sig>`. Do **not** prepend `Bearer `. The MCP server adds it. |
 | `YTB_MCP_PLATFORM` | No | Explicit platform hint: `wordpress` or `joomla`. Set to `joomla` when `YTB_MCP_SITE_URL` is an origin-only Joomla URL (no `/api/index.php/` in the path). Defaults to URL-shape auto-detection. |
 | `YTB_MCP_TIMEOUT_MS` | No | REST timeout (default 15000). |
 | `YTB_MCP_TEST_MODE` | No | `1` skips the stdio loop (smoke tests). |
+| `YTB_MCP_SITES_FILE` | No | Path to the multi-site registry (see "Multi-site setup" above). Defaults to `~/.config/yt-builder-mcp/sites.json`. |
+| `YTB_MCP_PROFILE` | No | Boots the server pinned to one `site_id` from the registry, for a one-MCP-entry-per-site setup. |
+| `YTB_MCP_EXTRA_HEADERS` | No | Extra HTTP headers merged into every outbound request (a WAF cookie, a corporate gateway secret, HTTP Basic-Auth, …). Either a JSON object (`{"X-WAF-Token":"abc"}`) or `Name: value` lines. An `Authorization` entry here is always dropped — the Bearer owns that header. |
+| `YTB_MCP_SITE_BASIC_AUTH` | No | `user:pass` for a site fronted by an HTTP Basic-Auth realm. Sent as the `Authorization: Basic …` header; the plugin Bearer then travels on `X-Authorization`. |
+| `YTB_MCP_VERSION` | No | Version-pin fallback used when `--pin` isn't passed at setup time (see "Corporate TLS interception / air-gapped installs"). |
 
 ## Manual MCP config (no wizard)
 
@@ -195,6 +211,58 @@ For a Joomla install at an origin-only URL, also set the platform hint:
 }
 ```
 
+## Multi-site setup (more than one WordPress/Joomla site)
+
+Instead of one `env` block per AI client, add every site once to a
+shared on-disk registry and address each by `site_id`:
+
+```bash
+npx -y @wootsup/yt-builder-mcp add-site \
+  --url https://shop.example.com --token "$YTB_TOKEN" \
+  --label "Shop" --site-id shop --default
+
+npx -y @wootsup/yt-builder-mcp add-site \
+  --url https://blog.example.com --token-ref "op://Vault/blog/token" \
+  --label "Blog" --site-id blog
+
+npx -y @wootsup/yt-builder-mcp list-sites
+npx -y @wootsup/yt-builder-mcp test-site shop
+npx -y @wootsup/yt-builder-mcp set-default blog
+npx -y @wootsup/yt-builder-mcp remove-site blog
+```
+
+`add-site` flags:
+
+| Flag | Required? | Description |
+|------|-----------|-------------|
+| `--url <site-url>` | Yes | Site base URL (WordPress or Joomla). |
+| `--token <bearer>` | One of these two | Plain Bearer key. Mutually exclusive with `--token-ref`. |
+| `--token-ref <op://…>` | One of these two | 1Password Secret Reference (`op://<vault>/<item>/<field>`) instead of a plain-text key. |
+| `--platform auto\|wordpress\|joomla` | No (default `auto`) | Explicit platform hint; `auto` is runtime-detected on first use. |
+| `--label "<text>"` | No | Human-readable label shown by `list-sites`. |
+| `--site-id <slug>` | No (default `default`) | Registry key used by every other multi-site command and by a tool call's optional `site_id` argument. |
+| `--default` | No | Mark this site as the default (the first added site becomes default automatically). |
+| `--yes` | No | Overwrite an existing `site_id` instead of failing. |
+| `--sites-file <path>` | No | Registry file to write, overriding `YTB_MCP_SITES_FILE` / the default path for this one call. |
+
+The registry lives at `~/.config/yt-builder-mcp/sites.json`
+(`$XDG_CONFIG_HOME/yt-builder-mcp/sites.json` when that variable is
+set). `YTB_MCP_SITES_FILE` is the switch that makes the server READ a
+registry at all: without it the server ignores `sites.json` entirely and
+runs off the single-site `YTB_MCP_SITE_URL` / `YTB_MCP_BEARER_TOKEN`
+pair. `setup` writes it for you, pointing at the registry it filled; set
+it by hand only to name a different path. When the file it names is
+missing or holds no sites, the server falls back to the single-site pair,
+so an unpopulated registry never costs you a working config.
+`YTB_MCP_PROFILE=<site_id>` boots the server
+pinned to one site from the registry — useful when you'd rather run
+one MCP entry per site than one shared multi-site entry.
+
+`uninstall` (alias `remove`) accepts `--all` (every detected client +
+the skill, no prompts), `--yes`/`-y` (skip the final confirmation),
+`--keep-skill` (remove client entries but leave the installed skill in
+place), and `--force`.
+
 ## Non-interactive CI usage
 
 For scripted / CI installs, pass the answers as flags and add
@@ -222,6 +290,36 @@ The wizard still runs its plugin-health + auth probes and uses the
 exit codes documented in the table below, so CI can branch on the
 exit code to detect whether the install actually succeeded.
 
+### Corporate TLS interception / air-gapped installs
+
+| Flag | Description |
+|------|-------------|
+| `--ca <path>` | Trust a corporate root CA `.pem` (writes `NODE_EXTRA_CA_CERTS=<path>` into the generated client config). |
+| `--use-system-ca` (or `--ca=system`) | Trust the OS certificate store instead of an exported file — zero-export, needs Node ≥ 22.15 (writes `NODE_OPTIONS=--use-system-ca`). |
+| `--pin <version>` | Pin the generated client config to an exact version (`npx -y @wootsup/yt-builder-mcp@<version>`) instead of the floating `@latest`. Falls back to the `YTB_MCP_VERSION` env var when omitted. |
+
+The interactive wizard auto-offers `--ca` / `--use-system-ca` the
+moment a probe fails with a TLS-inspection certificate error, so these
+flags are mainly for the non-interactive/CI path.
+
+### One-click setup (pickup mode)
+
+The host plugin's admin UI can hand the wizard a freshly-minted Bearer
+key directly, skipping the URL/token prompts entirely:
+
+```bash
+npx -y @wootsup/yt-builder-mcp setup \
+  --pickup https://example.com/wp-json/yt-builder-mcp/v1/setup/pickup \
+  --nonce "$NONCE" \
+  --client claude-desktop
+```
+
+The pickup URL and nonce are revealed together in wp-admin → Tools →
+"MCP for YOOtheme Pro" (WordPress) or Administrator → Components →
+"MCP for YOOtheme Pro" (Joomla). The pickup is IP-bound, single-use, and
+expires after 5 minutes; any `--url`/`--token` passed alongside
+`--pickup` are ignored (with a stderr warning).
+
 ## Exit codes (CLI)
 
 The CLI returns POSIX-style exit codes for scripting / CI:
@@ -234,15 +332,16 @@ The CLI returns POSIX-style exit codes for scripting / CI:
 | 3 | Auth probe failed and user declined to continue |
 | 4 | Write failed; configs rolled back |
 | 5 | Handshake failed; configs rolled back |
+| 6 | AI clients configured, but the site could not be recorded in `sites.json`; nothing rolled back |
 | 99 | Unhandled fatal in dispatcher |
 | 130 | User cancelled (SIGINT) |
 
 ## Documentation
 
-- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md): 5 canonical workflows, gateway model, tool catalog
+- [SKILL.md (bundled agent skill)](./skills/yt-builder-mcp/SKILL.md): 6 canonical workflows, gateway model, tool catalog
 - [REST API Reference](https://wootsup.com/docs/mcp/yootheme-wordpress/)
 - [MCP Tool Reference](https://wootsup.com/docs/mcp/yootheme-wordpress/tools)
 
-## Repository
+## Product page
 
-https://github.com/wootsup/yt-builder-mcp
+https://wootsup.com/products/yt-builder/

package/bin/node-floor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Type declaration for `node-floor.js`.
+ *
+ * That file is deliberately plain JavaScript outside the `src/` tree — its
+ * own docblock explains why: it guards the import that would otherwise throw
+ * while the module graph is being instantiated. `tsconfig.tests.json` still
+ * type-checks the tests that import it, and a `.js` module with no sibling
+ * declaration types as `any` there (TS7016) — this file is that declaration,
+ * kept in sync with the implementation by hand since the source itself
+ * cannot carry types without becoming the thing it guards against.
+ *
+ * @license MIT
+ */
+
+export declare const NODE_PREFLIGHT_FLOOR: readonly [number, number, number];
+export declare const UNSUPPORTED_NODE_MAJOR: number;
+export declare const NODE_TOO_OLD_EXIT: number;
+export declare const NODE_UNSUPPORTED_LINE_EXIT: number;
+
+export interface NodeRuntimeRefusal {
+    readonly exitCode: number;
+    readonly message: string;
+}
+
+export declare function nodeRuntimeRefusal(
+    versionString: string,
+    floor?: readonly [number, number, number],
+): NodeRuntimeRefusal | null;

package/bin/node-floor.js

@@ -0,0 +1,150 @@
+/**
+ * Refuse to run on a Node this package cannot work on, and say so in words the
+ * reader can act on.
+ *
+ * Why this cannot live in `dist/`: a dependency of the setup wizard uses a
+ * terminal-formatting helper from a Node builtin. Where the helper is missing
+ * entirely, importing it throws while the module graph is being INSTANTIATED,
+ * not when the code runs — so every subcommand dies, `--version` included,
+ * before a single line of ours executes. Anything that diagnoses that
+ * situation must therefore sit OUTSIDE the graph it diagnoses: this file is
+ * plain JavaScript, imports nothing, and is loaded before the first `dist/`
+ * module.
+ *
+ * The consequence for the floor number: it is duplicated here, because the
+ * authoritative `NODE_FLOOR` lives behind exactly the import this guard runs
+ * ahead of. `tests/setup/engines-floor.test.ts` holds the two together — the
+ * duplication is deliberate and watched, not an oversight.
+ *
+ * ## Where the number comes from, and where it does NOT
+ *
+ * The floor is a product decision, not the lowest version that happens to
+ * work — those are two different numbers and this file has held both.
+ *
+ * What it is TODAY: 22.15.0, the release that first reads the OS trust store
+ * via `--use-system-ca`. `SYSTEM_CA_NODE_FLOOR` in
+ * `src/diagnostics/ca-trust.ts` carries the same triple. Beneath it the
+ * wizard's automatic recovery for a corporate TLS-inspection proxy is a
+ * silent no-op, so a customer would be told a fix was applied that cannot
+ * work. The minor matters; 22.0 would reopen exactly that gap.
+ *
+ * What it WAS, and why the measurement still matters: the lowest version this
+ * package was ever observed to run on is 20.13.0, one minor ABOVE what the
+ * wizard's prompt library declares for itself. That library says `>= 20.12.0`
+ * and is wrong — it calls a terminal-formatting helper with an ARRAY of
+ * styles, an overload that arrived later than the helper. Measured 2026-08-31
+ * by bisection over nine installed releases, each confirmed against the real
+ * wizard and not only against the helper:
+ *
+ *   20.12.0  helper present, array form REJECTED  → wizard dies at the first prompt
+ *   20.13.0  array form accepted                  → wizard runs
+ *   21.0.0   helper ABSENT                        → module fails to load
+ *   21.7.3   helper present, array form REJECTED  → wizard dies at the first prompt
+ *   22.0.0   array form accepted                  → wizard runs
+ *
+ * That table is why the 21 line is refused on its own terms below. The
+ * supported set was never one interval: the overload was backported into the
+ * 20 line from 20.13.0 and never into the 21 line at all, and 21.7.3 was that
+ * line's last release. Today's floor already excludes 21 arithmetically, so
+ * the separate refusal survives for its WORDING, not for its reach.
+ *
+ * @license MIT
+ */
+
+/**
+ * Minimum supported Node. Kept equal to `NODE_FLOOR` in
+ * `src/diagnostics/doctor.ts` by `tests/setup/engines-floor.test.ts`.
+ */
+export const NODE_PREFLIGHT_FLOOR = [22, 15, 0];
+
+/**
+ * Major version of the line that never received the backport (see above).
+ *
+ * It sits BELOW the floor, so `engines.node` now excludes it too and npm does
+ * warn before installing — which it did not while the floor was in the 20
+ * line, and that older situation is the one this constant was built for. What
+ * survives the change is the WORDING: a customer who ignores the npm warning
+ * and starts anyway is told that this whole line is unusable and that no
+ * release of it will do, rather than being told to install something newer —
+ * advice that reads as "try 21.7.3" to anyone on 21.0.0.
+ *
+ * Removing it would therefore lose an explanation, not a refusal. The refusal
+ * is covered twice; the reason is not.
+ */
+export const UNSUPPORTED_NODE_MAJOR = 21;
+
+/**
+ * Exit codes. Both mean "this interpreter cannot run the package", and they
+ * are distinct so a caller can tell WHICH refusal it hit without parsing
+ * prose. Neither collides with the CLI's generic fatal (99) or with any code
+ * `runCli` returns (0, 1, 2, 130). The values are the conventional
+ * `EX_CONFIG` and `EX_UNAVAILABLE` from sysexits.
+ */
+export const NODE_TOO_OLD_EXIT = 78;
+export const NODE_UNSUPPORTED_LINE_EXIT = 69;
+
+const RESTART_HINT = 'then run the command again. If an AI client starts this server for you,\n'
+    + 'restart that client afterwards so it picks up the newer Node.\n';
+
+/**
+ * The refusal for `versionString`, or `null` when this Node can run the
+ * package.
+ *
+ * Returns the exit code alongside the message so the caller never has to
+ * decide which refusal it is holding.
+ *
+ * Takes the version as an argument rather than reading `process.version` so
+ * the decision is testable on any machine, against any version.
+ *
+ * **An unparseable version is allowed through, deliberately.** Blocking would
+ * turn an unrecognised-but-working runtime into a refusal to start, which is
+ * worse than the confusing loader error the caller would otherwise get: that
+ * error is the behaviour this guard replaces, not one it introduces.
+ */
+export function nodeRuntimeRefusal(versionString, floor = NODE_PREFLIGHT_FLOOR) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)/.exec(String(versionString ?? ''));
+    if (m === null) return null;
+
+    const found = [Number(m[1]), Number(m[2]), Number(m[3])];
+    const shown = found.join('.');
+
+    // Checked before the floor so this line gets its own explanation rather
+    // than the generic too-old refusal. The order was once load-bearing —
+    // every release of the line sat numerically ABOVE the floor, so nothing
+    // else would have caught it. It no longer is, and the check is kept for
+    // what it SAYS.
+    if (found[0] === UNSUPPORTED_NODE_MAJOR) {
+        // What to install is the HIGHER of "the line after the refused one"
+        // and the floor — never the former alone. With a floor of 22.15.0,
+        // advising "Node.js 22" would send the reader to a release this same
+        // function refuses one branch below, and they would meet a second
+        // refusal for a version they installed on our advice.
+        const advice = floor[0] > UNSUPPORTED_NODE_MAJOR
+            ? `${floor[0]}.${floor[1]}`
+            : String(UNSUPPORTED_NODE_MAJOR + 1);
+
+        return {
+            exitCode: NODE_UNSUPPORTED_LINE_EXIT,
+            message: `yt-builder-mcp cannot run on the Node.js ${UNSUPPORTED_NODE_MAJOR} line, `
+                + `and this is Node.js ${shown}.\n`
+                + `\n`
+                + `No Node.js ${UNSUPPORTED_NODE_MAJOR} release carries the terminal formatting this package\n`
+                + `needs. Install Node.js ${advice} or newer (an LTS release is recommended),\n`
+                + RESTART_HINT,
+        };
+    }
+
+    for (let i = 0; i < 3; i++) {
+        if (found[i] > floor[i]) return null;
+        if (found[i] < floor[i]) {
+            return {
+                exitCode: NODE_TOO_OLD_EXIT,
+                message: `yt-builder-mcp needs Node.js ${floor.join('.')} or newer, but this is Node.js ${shown}.\n`
+                    + `\n`
+                    + `Install Node.js ${floor[0]}.${floor[1]} or newer (an LTS release is recommended),\n`
+                    + RESTART_HINT,
+            };
+        }
+    }
+    return null;
+}

package/bin/yt-builder-mcp.js

@@ -9,11 +9,14 @@
  *                `remove-site` / `set-default` / `test-site` / `help` /
  *                `--help` / `-h` / `--version` / `-v`): forward argv to
  *                `runCli()` in `dist/setup-cli.js` (Wave G.7).
- *   - 'hint'   → no OR unknown subcommand AND stdin is an interactive TTY
+ *   - 'unknown'→ a word was given and it is not one of ours: name it back,
+ *                suggest the likely command, exit 2. Both at a terminal and
+ *                off one — no MCP client passes a word we do not know.
+ *   - 'hint'   → NO subcommand AND stdin is an interactive TTY
  *                (a human ran the bin directly): print a discoverability
  *                hint to stderr and exit 0, instead of silently blocking
  *                on the stdio read loop ("hang").
- *   - 'server' → no OR unknown subcommand AND stdin is NOT a TTY (a real
+ *   - 'server' → NO subcommand AND stdin is NOT a TTY (a real
  *                AI client piping JSON-RPC over stdin): import
  *                `dist/index.js`, which starts the MCP stdio server (or,
  *                under YTB_MCP_TEST_MODE=1, prints the tool list to stderr
@@ -44,20 +47,23 @@
  *
  * @license MIT
  */
-import { argv, stdin, stderr, exit } from 'node:process';
+import { argv, stdin, stderr, exit, version } from 'node:process';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
-import {
+import { nodeRuntimeRefusal } from './node-floor.js';
+
+// Dynamic, not static: a static import is hoisted above everything in this
+// file, so nothing written here could run ahead of it. This is the ONLY
+// `dist/` module loaded before the runtime check below, and it is loaded
+// because the check needs to know the route first.
+const {
     decideInvocation,
     isKnownSubcommand,
     BARE_INVOCATION_HINT,
-} from '../dist/cli/invocation-decision.js';
-import {
-    decideCaReexec,
-    CA_REEXEC_SENTINEL,
-    USE_SYSTEM_CA_FLAG,
-} from '../dist/diagnostics/ca-reexec.js';
+    unknownSubcommandMessage,
+    UNKNOWN_SUBCOMMAND_EXIT_CODE,
+} = await import('../dist/cli/invocation-decision.js');
 
 const args = argv.slice(2);
 const subcommand = args[0];
@@ -75,6 +81,31 @@ if (isKnownSubcommand(subcommand)) {
     action = decideInvocation(subcommand, stdin.isTTY);
 }
 
+// The runtime check applies to the routes a PERSON drives, never to the
+// server. Measured: `dist/index.js` loads on every version from the oldest
+// supported upwards, so the server never needed this floor — only the setup
+// wizard's terminal-formatting dependency does. Refusing the server route
+// would take a working MCP server away from a customer whose only real
+// problem is that `setup` cannot run.
+//
+// The cost of standing here rather than at the top of the file, stated so
+// nobody has to rediscover it: the check is no longer ahead of every `dist/`
+// import. Two are outside it — `invocation-decision.js` above, which must
+// load to decide the route at all, and `index.js` on the server branch,
+// which is deliberately unguarded. Should either ever pull in the wizard's
+// dependency, directly or through one of its own, that import throws while
+// the module graph is instantiated and this check never gets to speak: the
+// customer is back to a message about a missing module export. Both are
+// small and neither imports the wizard today, which is a measurement, not a
+// guarantee.
+if (action !== 'server') {
+    const refusal = nodeRuntimeRefusal(version);
+    if (refusal !== null) {
+        stderr.write(refusal.message);
+        exit(refusal.exitCode);
+    }
+}
+
 if (action === 'cli') {
     try {
         const { runCli } = await import('../dist/setup-cli.js');
@@ -85,6 +116,11 @@ if (action === 'cli') {
         stderr.write(`yt-builder-mcp: fatal: ${msg}\n`);
         exit(99);
     }
+} else if (action === 'unknown') {
+    // A word that is not ours. Said out loud, with a non-zero code — the two
+    // things a customer who mistyped needs and used to get neither of.
+    stderr.write(`${unknownSubcommandMessage(subcommand)}\n`);
+    exit(UNKNOWN_SUBCOMMAND_EXIT_CODE);
 } else if (action === 'hint') {
     stderr.write(`${BARE_INVOCATION_HINT}\n`);
     exit(0);
@@ -99,6 +135,11 @@ if (action === 'cli') {
     // normal in-process start — a re-exec failure must never break startup.
     if (process.env.YTB_MCP_TEST_MODE !== '1') {
         try {
+            const {
+                decideCaReexec,
+                CA_REEXEC_SENTINEL,
+                USE_SYSTEM_CA_FLAG,
+            } = await import('../dist/diagnostics/ca-reexec.js');
             const shouldReexec = decideCaReexec({
                 nodeVersion: process.version,
                 execArgv: process.execArgv,