@pymodel/niblet 0.3.2 → 0.4.1

package/README.md

@@ -80,9 +80,9 @@ Or use the equivalent host configuration:
 }
 ```
 
-The local adapter's three catalogue tools call REST `/v1`, not hosted MCP. They require an operator token for the configured self-hosted deployment; public `niblet_at_…` account keys do not authenticate `/v1`. Set `NIBLET_TOKEN`, `NIBLET_API_ORIGIN`, and `NIBLET_MEDIA_ORIGIN` in the host environment only when targeting that deployment.
+The local adapter's three catalogue tools call REST `/v1`, not hosted MCP. Public `niblet_at_…` account keys created at [niblet.com/account](https://www.niblet.com/account) authorize both `/v1` and `/mcp`. Set `NIBLET_TOKEN` to that key, plus `NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN` only when targeting a self-hosted deployment. Skill resources, `niblet_help`, and `niblet_status` configuration remain available with no token.
 
-**Ownership decision:** keep public, account-key catalogue access in the hosted HTTP MCP. Keep bundled resources, playbook prompts, local diagnostics, and the optional self-hosted REST bridge in this stdio adapter. Do not proxy hosted MCP through this package or add its local-only surfaces to the hosted service; keep only the three shared catalogue contracts in lockstep.
+**Ownership decision:** keep public, account-key catalogue access in the hosted HTTP MCP. Keep bundled resources, playbook prompts, local diagnostics, and the optional REST bridge in this stdio adapter. Do not proxy hosted MCP through this package or add its local-only surfaces to the hosted service; keep only the three shared catalogue contracts in lockstep.
 
 Node.js 24.15+; npx fetches the package on first launch. Keep every token in the host's secret/environment facility, never in a committed file or chat message.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pymodel/niblet",
-  "version": "0.3.2",
+  "version": "0.4.1",
   "description": "Niblet MCP server and design skill: real UI screen references for coding agents",
   "keywords": [
     "mcp",

package/skill/niblet/SKILL.md

@@ -3,12 +3,12 @@ name: niblet
 description: Keep interface work anchored to the product it belongs to instead of a generic template. Sets a short design contract, builds from the components and tokens already in the codebase, covers the states a surface can actually reach, and closes by looking at the rendered result. Use when building, reworking, or assessing a web or native interface. Trigger with "niblet", "niblet skill", "niblet designer ui", or "niblet review". Skip backend, CLI, data, and infrastructure work, prose-only tasks, and questions the product's own design system already settles.
 license: Apache-2.0
 metadata:
-  version: "0.3.1"
-  author: "Mohamed Elkholy (elkaix)"
-  organization: "PyModel"
-  source: "https://github.com/PyModel/niblet-skill-mcp"
-  compatibility: "Claude Code, Codex, Cursor, and GitHub Copilot, or any agent that can open repository files and call an MCP tool."
-  tags: "interface-design, product-ui, design-contract, state-coverage, accessibility, native"
+  version: '0.4.1'
+  author: 'Mohamed Elkholy (elkaix)'
+  organization: 'PyModel'
+  source: 'https://github.com/PyModel/niblet-skill-mcp'
+  compatibility: 'Claude Code, Codex, Cursor, and GitHub Copilot, or any agent that can open repository files and call an MCP tool.'
+  tags: 'interface-design, product-ui, design-contract, state-coverage, accessibility, native'
 ---
 
 # Niblet
@@ -31,12 +31,12 @@ Build an interface that belongs to this product, not a generic template. [Niblet
 
 Choose by the job of each surface, not the repository's category. Different surfaces in one product may use different modes. Persist the choice only in that surface's brief when persistence is requested; do not impose a project-wide mode.
 
-| Mode | User's job | Design priority | Common surfaces |
-| --- | --- | --- | --- |
-| **Persuade** | Decide and act | Make the proposition, evidence, trade-offs, and next action understandable | Marketing, pricing, acquisition |
-| **Operate** | Complete a task | Legible state, efficient controls, predictable navigation, and recovery | Apps, dashboards, settings, native utilities |
-| **Read** | Understand | Comprehension, typography, reading rhythm, navigation, and useful examples | Documentation, articles, guides |
-| **Experience** | Engage with the work itself | Let the artifact lead; keep navigation and chrome subordinate but usable | Portfolios, galleries, interactive work |
+| Mode           | User's job                  | Design priority                                                            | Common surfaces                              |
+| -------------- | --------------------------- | -------------------------------------------------------------------------- | -------------------------------------------- |
+| **Persuade**   | Decide and act              | Make the proposition, evidence, trade-offs, and next action understandable | Marketing, pricing, acquisition              |
+| **Operate**    | Complete a task             | Legible state, efficient controls, predictable navigation, and recovery    | Apps, dashboards, settings, native utilities |
+| **Read**       | Understand                  | Comprehension, typography, reading rhythm, navigation, and useful examples | Documentation, articles, guides              |
+| **Experience** | Engage with the work itself | Let the artifact lead; keep navigation and chrome subordinate but usable   | Portfolios, galleries, interactive work      |
 
 Mode is a prioritization tool, not a visual preset. A pricing page still needs usable controls; a gallery still needs accessible navigation; an application can have character without obscuring its tasks.
 

package/skill/niblet/references/connection.md

@@ -8,7 +8,7 @@ The skill can work from the repository, product brief, and supplied screenshots
 
 ## Local stdio MCP package
 
-Prerequisite: Node.js **24.15 or later**. The adapter's bundled documents, `niblet_help`, and `niblet_status` work without a token. Its three catalogue tools call the configured REST `/v1` API and therefore need that deployment's **operator token**. A public `niblet_at_…` account key authenticates the hosted MCP endpoint instead; `/v1` rejects it.
+Prerequisite: Node.js **24.15 or later**. The adapter's bundled documents, `niblet_help`, and `niblet_status` work without a token. Its three catalogue tools call REST `/v1`. A public `niblet_at_…` account key created at [niblet.com/account](https://www.niblet.com/account) authorizes both `/v1` and hosted `/mcp`.
 
 The shortest local configuration uses the published package:
 
@@ -31,23 +31,23 @@ For a host using the common `mcpServers` JSON configuration shape:
 
 Adapt the shape to the host's documented configuration. The bundled `mcp.json` contains this token-free template; it does not load `.env`.
 
-For catalogue access against a self-hosted deployment, add `NIBLET_TOKEN` with that deployment's operator token plus `NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN`. Prefer a host-managed secret/environment facility and keep tokens out of commits, screenshots, queries, and chat. From a source checkout, a manual environment-file launch is `node --env-file=/absolute/path/to/private.env src/index.mjs`; plain `npm start` only inherits its process environment.
-
-Public catalogue access should use the hosted MCP endpoint with an account key created at `https://www.niblet.com/account`; do not put that account key in this adapter's `NIBLET_TOKEN`.
+Niblet itself is a hosted service — there is nothing to self-host. For catalogue access, point this adapter at the hosted API: set `NIBLET_TOKEN` to an account key created at `https://www.niblet.com/account` (one key works on the REST catalogue and the MCP endpoint alike), and leave `NIBLET_API_ORIGIN` and `NIBLET_MEDIA_ORIGIN` unset for the hosted defaults. Prefer a host-managed secret/environment facility and keep keys out of commits, screenshots, queries, and chat. From a source checkout, a manual environment-file launch is `node --env-file=/absolute/path/to/private.env src/index.mjs`; plain `npm start` only inherits its process environment.
 
 The package contacts `https://api.niblet.com` by default, or the HTTP(S) origin in `NIBLET_API_ORIGIN`. It sends the token as bearer authentication for API requests, and never to the media origin. `NIBLET_TOKEN` configures this local adapter; it is not automatically a remote HTTP client's authentication setting.
 
-After the host starts the entry, inspect its observed tool, resource, and prompt inventory. A saved configuration is not proof of a connection. `niblet://skill` and the four `niblet://skill/{commands,connection,evidence,native}` resources return the bundled documents without a token. The local adapter also registers every playbook entry as an MCP prompt named `niblet-<command>`. Catalogue calls require the operator token described above.
+After the host starts the entry, inspect its observed tool, resource, and prompt inventory. A saved configuration is not proof of a connection. `niblet://skill` and the four `niblet://skill/{commands,connection,evidence,native}` resources return the bundled documents without a token. The local adapter also registers every playbook entry as an MCP prompt named `niblet-<command>`. Catalogue calls require a key — against the hosted service, an account key from `/account`.
+
+If a catalogue tool fails, read the error: it tells you whether to relay a config change to the user (missing, unexpanded, or placeholder token; website origin instead of `api.niblet.com`) or to continue from `niblet://skill` without retrying. Do not conclude the catalogue is empty from an authentication failure. Hosted MCP at `https://api.niblet.com/mcp` is the other door for the same key; it does not expose `niblet_help` or `niblet_status`.
 
 ### Tool inputs
 
 Tool arguments use **`query`**, not `q`. The adapter translates `query` to the REST API's `q` query parameter. Omitted optional fields use the defaults below.
 
-| Tool | Required arguments | Optional arguments | Returned data |
-| --- | --- | --- | --- |
-| `find_ui_references` | `query`: string, 1–240 characters | `platform`: `ios` or `web`; `limit`: integer 1–3, default 2; `selectedIds`: one to three screen IDs, each 1–160 characters; `clientSkillVersion`: string, 1–64 characters | Human-readable reference lines and images in `content`; typed references in `structuredContent` |
-| `find_ui_materials` | `query`: string, 1–240 characters; `kind`: `font`, `icon`, `animated_icon`, or `pack` | `platform`: `ios` or `web`; `limit`: integer 1–3, default 2; `selectedId`: string, 1–160 characters; `userConfirmed`: `true`; `clientSkillVersion`: string, 1–64 characters | Human-readable materials in `content`; typed name, license, description, and URL records in `structuredContent` |
-| `get_design_reference` | one of `screenId` (from a reference) or `packSlug` | `sections`: one or more of `overview`, `colors`, `typography`, `components`, `provenance`; `clientSkillVersion`: string, 1–64 characters | The requested markdown in `content`; typed slug, name, theme, markdown, and returned section names in `structuredContent` |
+| Tool                   | Required arguments                                                                    | Optional arguments                                                                                                                                                          | Returned data                                                                                                             |
+| ---------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `find_ui_references`   | `query`: string, 1–240 characters                                                     | `platform`: `ios` or `web`; `limit`: integer 1–3, default 2; `selectedIds`: one to three screen IDs, each 1–160 characters; `clientSkillVersion`: string, 1–64 characters   | Human-readable reference lines and images in `content`; typed references in `structuredContent`                           |
+| `find_ui_materials`    | `query`: string, 1–240 characters; `kind`: `font`, `icon`, `animated_icon`, or `pack` | `platform`: `ios` or `web`; `limit`: integer 1–3, default 2; `selectedId`: string, 1–160 characters; `userConfirmed`: `true`; `clientSkillVersion`: string, 1–64 characters | Human-readable materials in `content`; typed name, license, description, and URL records in `structuredContent`           |
+| `get_design_reference` | one of `screenId` (from a reference) or `packSlug`                                    | `sections`: one or more of `overview`, `colors`, `typography`, `components`, `provenance`; `clientSkillVersion`: string, 1–64 characters                                    | The requested markdown in `content`; typed slug, name, theme, markdown, and returned section names in `structuredContent` |
 
 Without `selectedIds`, `find_ui_references` searches and attaches thumbnail images. With `selectedIds`, it reads those exact screens and attaches inspection-quality images; an ID the catalogue does not hold is skipped rather than failing the call. `query` is required in both cases.
 
@@ -107,11 +107,11 @@ The remote service does not promise the `niblet://skill` resource. Neither deplo
 
 ## Capability checks and manual alternatives
 
-| Requested helper | Capability to inspect | Honest alternative |
-| --- | --- | --- |
-| `doctor` | Host connection state, runtime/path configuration, token presence, tool inventory | Explain the observed failed boundary and the needed configuration change; no bundled diagnostic executable |
-| `hooks` | Host-specific hook API and existing event configuration | Invoke the finish gate manually before handoff; no bundled hook installer |
-| `pin` / `unpin` | Host's documented command-shortcut registration | Invoke “Niblet <command> <target>” directly; no bundled shortcut installer |
-| `live` | Authorized browser/simulator session and available interaction tools | Work from supplied screenshots and targeted manual inspection; no bundled browser service or watcher |
+| Requested helper | Capability to inspect                                                             | Honest alternative                                                                                         |
+| ---------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `doctor`         | Host connection state, runtime/path configuration, token presence, tool inventory | Explain the observed failed boundary and the needed configuration change; no bundled diagnostic executable |
+| `hooks`          | Host-specific hook API and existing event configuration                           | Invoke the finish gate manually before handoff; no bundled hook installer                                  |
+| `pin` / `unpin`  | Host's documented command-shortcut registration                                   | Invoke “Niblet <command> <target>” directly; no bundled shortcut installer                                 |
+| `live`           | Authorized browser/simulator session and available interaction tools              | Work from supplied screenshots and targeted manual inspection; no bundled browser service or watcher       |
 
 The full task instructions for these helpers are in [the command playbook](commands.md). Confirm capabilities through real host results, not inferred availability from a command name.

package/src/server.mjs

@@ -51,18 +51,23 @@ function textResult(text, structuredContent) {
 }
 
 /**
- * A 401 is nearly always a token mismatch on the user's machine, so the message
- * says exactly what to check and asks the agent to relay it. The token itself is
- * never shown; its length is enough to tell two credentials apart.
+ * A 401 is nearly always a token or origin mismatch on the user's machine, so the
+ * message says exactly what to check and asks the agent to relay it. The token
+ * itself is never shown; its length is enough to tell two credentials apart.
  */
+const LOCAL_CONTINUE =
+  'Do not retry catalogue tools. Do not conclude the catalogue is empty. niblet_help and niblet://skill remain available without a key.';
+
 function authenticationFailed(token, apiOrigin) {
   const length = typeof token === 'string' ? token.trim().length : 0;
   return [
     `Niblet API authentication failed (HTTP 401): ${apiOrigin} rejected the configured NIBLET_TOKEN (${length} characters, not shown).`,
-    'Tell the user: the token this MCP server is running with is not one the API accepts.',
+    'Tell the user: the token this MCP server is running with is not one the API at that origin accepts.',
     'Most often a NIBLET_TOKEN exported in the shell (e.g. ~/.zshrc, ~/.zshrc.local) overrides the one in the MCP .env file, because node --env-file never replaces a variable that is already set.',
-    'To fix: make the shell export and the .env file agree (or remove the export), confirm the token matches the API at that origin, then restart the MCP server so it re-reads its environment.',
+    'Another cause is pointing this adapter at the wrong origin, or using a key from a different deployment.',
+    `To fix: create a key at https://www.niblet.com/account, set it as NIBLET_TOKEN (or connect the host to https://api.niblet.com/mcp with Authorization: Bearer niblet_at_…), make the shell export and the .env file agree (or remove the export), then restart the MCP server so it re-reads its environment.`,
     'Run niblet_status to confirm the fix.',
+    LOCAL_CONTINUE,
   ].join(' ');
 }
 
@@ -78,7 +83,14 @@ function retryAfterSeconds(value) {
 function httpError(status, context = {}) {
   if (status >= 300 && status < 400) return 'Niblet API redirects are not allowed.';
   if (status === 401) return authenticationFailed(context.token, context.apiOrigin);
-  if (status === 403) return 'Niblet API access denied (HTTP 403).';
+  if (status === 403) {
+    return [
+      'Niblet API access denied (HTTP 403).',
+      'Tell the user: this origin refused the request. That is often a WAF or a key that is not allowed on this path, not a missing catalogue.',
+      'To fix: use a niblet_at_ account key from https://www.niblet.com/account against https://api.niblet.com. Do not rotate the key unless the API said it was unrecognised.',
+      LOCAL_CONTINUE,
+    ].join(' ');
+  }
   if (status === 404) return 'The requested Niblet resource was not found (HTTP 404).';
   if (status === 429) {
     const seconds = retryAfterSeconds(context.retryAfter);
@@ -88,6 +100,74 @@ function httpError(status, context = {}) {
   return `Niblet API request failed (HTTP ${status}).`;
 }
 
+function originNote(apiOrigin) {
+  let host;
+  try {
+    host = new URL(apiOrigin).hostname;
+  } catch {
+    return null;
+  }
+  if (host === 'api.niblet.com' || host === 'localhost' || host === '127.0.0.1') return null;
+  if (wrongOriginMessage(apiOrigin)) return null;
+  return `Niblet API origin is ${host}, not api.niblet.com. Tell the user: confirm this is their own deployment. Catalogue calls will use this origin.`;
+}
+
+function leaksCredential(text, token) {
+  if (/&lt;|&#/i.test(text)) return true;
+  if (typeof token !== 'string' || token.trim() === '') return false;
+  const value = token.trim();
+  if (text.includes(value)) return true;
+  if (value.length >= 24 && text.includes(value.slice(8))) return true;
+  if (text.includes(Buffer.from(value).toString('base64'))) return true;
+  if (text.includes(encodeURIComponent(value))) return true;
+  return false;
+}
+
+async function messageFromErrorResponse(response, fallback, token) {
+  try {
+    const bytes = await readBounded(response);
+    const data = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    const body = data && typeof data === 'object' && typeof data.error === 'string' ? data.error.trim() : '';
+    if (!body || leaksCredential(body, token)) return fallback;
+    if (body.startsWith('Niblet API')) return body;
+    if (fallback.startsWith('Niblet API authentication failed')) {
+      return `Niblet API authentication failed (HTTP 401). ${body}`;
+    }
+    if (fallback.startsWith('Niblet API access denied')) {
+      return `Niblet API access denied (HTTP 403). ${body}`;
+    }
+    return body;
+  } catch {
+    return fallback;
+  }
+}
+
+function wrongOriginMessage(apiOrigin) {
+  let host;
+  try {
+    host = new URL(apiOrigin).hostname;
+  } catch {
+    return null;
+  }
+  if (host === 'niblet.com' || host === 'www.niblet.com') {
+    return [
+      `Niblet API origin is the public website (${host}), not the API.`,
+      'Tell the user: this MCP is pointed at niblet.com instead of api.niblet.com.',
+      'To fix: leave NIBLET_API_ORIGIN unset or set it to https://api.niblet.com, then restart this MCP server.',
+      LOCAL_CONTINUE,
+    ].join(' ');
+  }
+  if (host === 'media.niblet.com') {
+    return [
+      'Niblet API origin is the media host, not the API.',
+      'Tell the user: NIBLET_API_ORIGIN is set to the media origin.',
+      'To fix: set NIBLET_API_ORIGIN to https://api.niblet.com or unset it, then restart this MCP server.',
+      LOCAL_CONTINUE,
+    ].join(' ');
+  }
+  return null;
+}
+
 /** Read a bounded body into one buffer; the caller decides how to decode it. */
 async function readBounded(response) {
   const declaredLength = response.headers.get('content-length');
@@ -275,14 +355,44 @@ export function createServer({
 
   function credentialError() {
     if (typeof token !== 'string' || token.trim() === '') {
-      return 'NIBLET_TOKEN is required for Niblet API tools. Configure it in the MCP server environment. The niblet://skill resource remains available.';
+      return [
+        'NIBLET_TOKEN is required for Niblet catalogue tools.',
+        'Tell the user: this local MCP has no key, so search cannot run.',
+        'To fix: create a key at https://www.niblet.com/account, set NIBLET_TOKEN in the MCP server environment, then restart this server; or connect the host to https://api.niblet.com/mcp with Authorization: Bearer niblet_at_….',
+        LOCAL_CONTINUE,
+      ].join(' ');
+    }
+    if (/^\$\{?[A-Z0-9_]+\}?$/.test(token)) {
+      return [
+        'NIBLET_TOKEN is the literal environment-variable name, not a key.',
+        'Tell the user: the MCP config stored the variable name unexpanded.',
+        'To fix: put the key itself (it starts with niblet_at_) in the MCP server environment, then restart.',
+        LOCAL_CONTINUE,
+      ].join(' ');
+    }
+    if (token === 'YOUR_NIBLET_KEY' || /^(<|\[)?your[-_ ]?niblet[-_ ]?(key|token)(>|\])?$/i.test(token)) {
+      return [
+        'NIBLET_TOKEN is the setup placeholder, not a key.',
+        'Tell the user: they still have the example text in the MCP config.',
+        'To fix: create a key at https://www.niblet.com/account, put it in the MCP server environment, then restart.',
+        LOCAL_CONTINUE,
+      ].join(' ');
     }
     if (!/^[A-Za-z0-9._~+/-]+=*$/.test(token)) {
-      return 'NIBLET_TOKEN is not a valid bearer token. Check the MCP server environment.';
+      return [
+        'NIBLET_TOKEN is not a valid bearer token.',
+        'Tell the user: the configured value is not a usable key.',
+        'To fix: paste a niblet_at_ key from https://www.niblet.com/account into the MCP server environment, then restart.',
+        LOCAL_CONTINUE,
+      ].join(' ');
     }
     return null;
   }
 
+  function connectionError() {
+    return wrongOriginMessage(API_ORIGIN) || credentialError();
+  }
+
   /** One bounded, fixed-origin, authenticated GET. Resolves to {ok:true,data} or {ok:false,message,status}. */
   async function requestJson(segments, params, callerSignal) {
     if (callerSignal?.aborted) return { ok: false, message: 'Niblet API request was cancelled.' };
@@ -317,15 +427,20 @@ export function createServer({
       signal.throwIfAborted();
       if (response.redirected) throw new ApiError('Niblet API redirects are not allowed.');
       if (!response.ok) {
-        return {
-          ok: false,
-          message: httpError(response.status, {
-            token,
-            apiOrigin: API_ORIGIN,
-            retryAfter: response.headers.get('retry-after'),
-          }),
-          status: response.status,
-        };
+        const retryAfter = response.headers.get('retry-after');
+        const fallback = httpError(response.status, {
+          token,
+          apiOrigin: API_ORIGIN,
+          retryAfter,
+        });
+        let message = await messageFromErrorResponse(response, fallback, token);
+        if (response.status === 429) {
+          const seconds = retryAfterSeconds(retryAfter);
+          if (seconds !== null && !/Retry after/i.test(message)) {
+            message = `${message} Retry after ${seconds} seconds.`;
+          }
+        }
+        return { ok: false, message, status: response.status };
       }
       const data = await readJson(response);
       signal.throwIfAborted();
@@ -393,8 +508,8 @@ export function createServer({
     outputSchema: FindUiReferencesOutputSchema,
     annotations,
   }, async (input, extra) => {
-    const credential = credentialError();
-    if (credential) return errorResult(credential);
+    const connected = connectionError();
+    if (connected) return errorResult(connected);
 
     if (input.selectedIds?.length) {
       // Missing ids are omitted, and the remaining screens are numbered contiguously, as the catalogue does.
@@ -484,8 +599,8 @@ export function createServer({
         { materials: [], kind: input.kind },
       );
     }
-    const credential = credentialError();
-    if (credential) return errorResult(credential);
+    const connected = connectionError();
+    if (connected) return errorResult(connected);
 
     const result = await requestJson(['materials'], {
       q: input.query,
@@ -538,8 +653,8 @@ export function createServer({
     outputSchema: GetDesignReferenceOutputSchema,
     annotations,
   }, async (input, extra) => {
-    const credential = credentialError();
-    if (credential) return errorResult(credential);
+    const connected = connectionError();
+    if (connected) return errorResult(connected);
 
     const result = await requestJson(['design-reference'], {
       screenId: input.screenId,
@@ -632,7 +747,7 @@ export function createServer({
     }
     lines.push('', 'Reference documents (read as MCP resources):');
     for (const [slug, doc] of Object.entries(SKILL_DOCS)) lines.push(`  ${uriFor(slug)} — ${doc.title}`);
-    lines.push('', 'Catalogue tools: find_ui_references (real full-screen references), find_ui_materials (license-recorded fonts and icons), get_design_reference (the recorded colors, typography, and components behind a web screen). All three need NIBLET_TOKEN; run niblet_status to check. Reference retrieval is optional and never a prerequisite to useful work.');
+    lines.push('', 'Catalogue tools: find_ui_references (real full-screen references), find_ui_materials (license-recorded fonts and icons), get_design_reference (the recorded colors, typography, and components behind a web screen). All three need a niblet_at_ key as NIBLET_TOKEN, or connect the host to https://api.niblet.com/mcp with that key. Run niblet_status to check. Reference retrieval is optional and never a prerequisite to useful work.');
     lines.push('With no target or command, present this menu and wait for a choice rather than making changes.');
     return textResult(lines.join('\n'));
   });
@@ -650,9 +765,12 @@ export function createServer({
 
     // Presence and shape only — the playbook's doctor entry requires never displaying it.
     const credential = credentialError();
+    const originWrong = wrongOriginMessage(API_ORIGIN);
     if (typeof token !== 'string' || token.trim() === '') lines.push('Token:        not configured. Set NIBLET_TOKEN in the MCP server environment.');
     else if (credential) lines.push('Token:        present but malformed for a bearer credential. Check NIBLET_TOKEN.');
     else lines.push(`Token:        present (${token.trim().length} characters, not shown).`);
+    const note = originNote(API_ORIGIN);
+    if (note) lines.push(`Origin note:  ${note}`);
 
     const docs = await Promise.all(Object.keys(SKILL_DOCS).map(async (slug) => {
       try {
@@ -670,18 +788,17 @@ export function createServer({
       lines.push('', 'API not contacted (probe disabled).');
       return textResult(lines.join('\n'));
     }
-    if (credential) {
-      lines.push('', 'API not contacted: no usable token. The bundled documents and niblet_help remain available without one.');
+    if (originWrong || credential) {
+      lines.push('', originWrong || credential);
       return textResult(lines.join('\n'));
     }
 
     const result = await requestJson(['stats'], {}, extra.signal);
     if (!result.ok) {
       // Any HTTP status means the origin answered, which is what reachability asks.
-      // /v1/stats is not part of the hosted contract, so a 404 is a normal answer
-      // from a healthy deployment, not a failure.
+      // A 404 still means the origin is up; counts come from a current /v1/stats.
       if (result.status === 404) {
-        lines.push('', 'API check:    reachable — the configured origin answered. It does not serve catalogue counts; use find_ui_references to confirm the catalogue itself.');
+        lines.push('', 'API check:    reachable — the configured origin answered, but /v1/stats was not there. Tell the user: NIBLET_API_ORIGIN may point at the website or an old deployment, not https://api.niblet.com. To fix: unset NIBLET_API_ORIGIN for hosted, then restart this MCP server.');
         return textResult(lines.join('\n'));
       }
       if (result.status !== undefined) {