@linktr.ee/arbor-mcp 0.4.0 → 0.6.0

package/dist/index.js

@@ -6,7 +6,11 @@ var __getOwnPropNames = Object.getOwnPropertyNames;
 var __getProtoOf = Object.getPrototypeOf;
 var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __commonJS = (cb, mod) => function __require() {
-  return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  try {
+    return mod || (0, cb[__getOwnPropNames(cb)[0]])((mod = { exports: {} }).exports, mod), mod.exports;
+  } catch (e) {
+    throw mod = 0, e;
+  }
 };
 var __export = (target, all) => {
   for (var name in all)
@@ -33,7 +37,6 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 var require_rules = __commonJS({
   "../../docs/content/ux-writing/rules.json"(exports, module) {
     module.exports = {
-      $schema: "./types.schema.json",
       version: "1.0.0",
       description: "Static lint rules for UX writing. Consumable by Lambda, Figma plugin, Claude skill, and CI scripts.",
       rules: {
@@ -160,6 +163,86 @@ var require_rules = __commonJS({
               pattern: "are you sure",
               reason: "Patronizing. State consequences clearly instead.",
               suggestion: "Replace with clear consequence statement: 'This will delete all data'"
+            },
+            {
+              pattern: "\\btier\\b",
+              matchType: "regex",
+              label: "tier",
+              reason: 'Linktree plans are called "plans", not "tiers". "Tier" is internal language.',
+              suggestion: 'Use "plan" instead of "tier".'
+            },
+            {
+              pattern: "\\bPRO\\b",
+              matchType: "regex",
+              caseSensitive: true,
+              label: "PRO",
+              reason: 'Plan names use title case: "Pro", not "PRO".',
+              suggestion: 'Write the plan name as "Pro".'
+            },
+            {
+              pattern: "\\b(?:your|my|their|our|the|a|an|this|that)\\s+profiles?\\b(?!\\s+(?:photo|image|picture|avatar|url|link))",
+              matchType: "regex",
+              label: "profile",
+              reason: `Don't call a Linktree a generic "profile".`,
+              suggestion: 'Refer to it as your "Linktree" (the proper noun "Linktree Profile" is fine).'
+            },
+            {
+              pattern: "\\bpackage(s)?\\b",
+              matchType: "regex",
+              label: "package",
+              reason: 'Linktree plans are called "plans", not "packages".',
+              suggestion: 'Use "plan" instead of "package".'
+            },
+            {
+              pattern: "\\bbucket(s)?\\b",
+              matchType: "regex",
+              label: "bucket",
+              reason: 'Linktree plans are called "plans", not "buckets".',
+              suggestion: 'Use "plan" instead of "bucket".'
+            },
+            {
+              pattern: "\\busers?\\b(?!\\s*-?\\s*(?:friendly|name|names|generated|facing|flow|flows|journey|journeys|persona|personas|research|testing|experience|interface|story|stories))",
+              matchType: "regex",
+              label: "users",
+              reason: 'People who use Linktree are "Linkers", not "users".',
+              suggestion: 'Use "Linkers" \u2014 or just say "you".'
+            },
+            {
+              pattern: "\\bLink Tree\\b",
+              matchType: "regex",
+              label: "Link Tree",
+              reason: 'Linktree is one word: "Linktree", not "Link Tree".',
+              suggestion: 'Write it as "Linktree".'
+            },
+            {
+              pattern: "\\bLinkTree\\b",
+              matchType: "regex",
+              caseSensitive: true,
+              label: "LinkTree",
+              reason: 'Linktree capitalizes only the L: "Linktree", not "LinkTree".',
+              suggestion: 'Write it as "Linktree".'
+            },
+            {
+              pattern: "\\b(linkinbio|link-in-bio|bio link)\\b",
+              matchType: "regex",
+              label: "link-in-bio",
+              reason: `It's "link in bio" \u2014 three words, no hyphen.`,
+              suggestion: 'Use "link in bio" (not "linkinbio", "link-in-bio" or "bio link").'
+            },
+            {
+              pattern: "subscription",
+              reason: 'Linktree billing is a "plan", not a "subscription".',
+              suggestion: 'Use "plan". (Keep "subscribe"/"subscriber" for the visitor notification feature.)'
+            },
+            {
+              pattern: "utilize",
+              reason: "Formal and stiff. Plain language is friendlier.",
+              suggestion: 'Use "use" instead of "utilize".'
+            },
+            {
+              pattern: "facilitate",
+              reason: "Formal and stiff. Plain language is friendlier.",
+              suggestion: 'Use "help" instead of "facilitate".'
             }
           ]
         },
@@ -462,7 +545,7 @@ var require_patterns = __commonJS({
           examples: {
             do: [
               "Update required. This version is no longer supported. Update now to continue.",
-              "Subscription expired. Your account is paused. Renew subscription to restore access.",
+              "Plan expired. Your account is paused. Renew your plan to restore access.",
               "Verification needed. Confirm your email to access features. Check your inbox."
             ],
             dont: [
@@ -511,7 +594,7 @@ var require_patterns = __commonJS({
             do: [
               "Changes saved",
               "Email sent",
-              "Profile updated",
+              "Linktree updated",
               "You're all set",
               "You're officially a Pro!"
             ],
@@ -915,6 +998,7 @@ var require_engine = __commonJS({
     var contentTypesData = require_content_types();
     var rules = rulesData.rules;
     var scoring = rulesData.scoring;
+    var MIN_CONTENT_TYPE_CONFIDENCE = 30;
     var passiveVoiceRegex = new RegExp(
       rules["passive-voice"].check.pattern,
       "gi"
@@ -931,6 +1015,15 @@ var require_engine = __commonJS({
       }
       compiledTextPatterns.set(typeId, regexes);
     }
+    var compiledBannedPhrases = rules["banned-phrases"].phrases.map((phrase) => {
+      if (phrase.matchType !== "regex") return phrase;
+      try {
+        const flags = phrase.caseSensitive ? "" : "i";
+        return { ...phrase, _regex: new RegExp(phrase.pattern, flags) };
+      } catch {
+        return { ...phrase, _regex: null };
+      }
+    });
     function countSyllables(word) {
       const w = word.toLowerCase().replace(/[^a-z]/g, "");
       if (w.length <= 3) return 1;
@@ -946,34 +1039,42 @@ var require_engine = __commonJS({
     }
     function checkSentenceCase(text, issues) {
       const words = text.split(/\s+/);
-      for (let i = 1; i < words.length; i++) {
-        const word = words[i].replace(/[^a-zA-Z]/g, "");
-        if (word === "I" || /^[^a-zA-Z]*I['\u2019\u2018]/.test(words[i])) continue;
-        if (word.length > 0 && word[0] === word[0].toUpperCase() && word[0] !== word[0].toLowerCase() && !properNounAllowlist.has(word)) {
-          issues.push({
-            ruleId: "sentence-case",
-            ruleName: "Sentence case",
-            severity: "warning",
-            message: `"${word}" appears capitalized. Use sentence case for UI text.`,
-            suggestion: `Change to "${word.toLowerCase()}"`
-          });
-          break;
+      let sentenceStart = true;
+      for (let i = 0; i < words.length; i++) {
+        const raw = words[i];
+        if (!raw) continue;
+        const endsSentence = /[.!?][)\]"'\u2019\u201d]*$/.test(raw);
+        if (!sentenceStart) {
+          const word = raw.replace(/^[^a-zA-Z]+/, "").replace(/[^a-zA-Z]+$/, "");
+          const isPronounI = word.replace(/[^a-zA-Z]/g, "") === "I" || /^[^a-zA-Z]*I['\u2019\u2018]/.test(raw);
+          if (!isPronounI && word.length > 0 && word[0] === word[0].toUpperCase() && word[0] !== word[0].toLowerCase() && !properNounAllowlist.has(word)) {
+            const sentenceCased = word === word.toUpperCase() ? word.toLowerCase() : word[0].toLowerCase() + word.slice(1);
+            issues.push({
+              ruleId: "sentence-case",
+              ruleName: "Sentence case",
+              severity: "warning",
+              message: `"${word}" appears capitalized. Use sentence case for UI text.`,
+              suggestion: `Change to "${sentenceCased}"`
+            });
+            break;
+          }
         }
+        sentenceStart = endsSentence;
       }
     }
     function checkBannedPhrases(text, contentType, issues) {
       const lower = text.toLowerCase();
-      for (const phrase of rules["banned-phrases"].phrases) {
-        if (lower.includes(phrase.pattern)) {
-          const severity = contentType === "button" ? rules["banned-phrases"].severityByContext.button : rules["banned-phrases"].severityByContext.other;
-          issues.push({
-            ruleId: "banned-phrases",
-            ruleName: "Banned phrase",
-            severity,
-            message: `"${phrase.pattern}" \u2014 ${phrase.reason}`,
-            suggestion: phrase.suggestion
-          });
-        }
+      for (const phrase of compiledBannedPhrases) {
+        const matched = phrase.matchType === "regex" ? phrase._regex !== null && phrase._regex.test(text) : lower.includes(phrase.pattern);
+        if (!matched) continue;
+        const severity = contentType === "button" ? rules["banned-phrases"].severityByContext.button : rules["banned-phrases"].severityByContext.other;
+        issues.push({
+          ruleId: "banned-phrases",
+          ruleName: "Banned phrase",
+          severity,
+          message: `"${phrase.label || phrase.pattern}" \u2014 ${phrase.reason}`,
+          suggestion: phrase.suggestion
+        });
       }
     }
     function checkGenericButtons(text, issues) {
@@ -1113,6 +1214,9 @@ var require_engine = __commonJS({
           bestMatch = { type: typeId, confidence: score };
         }
       }
+      if (!bestMatch || bestMatch.confidence < MIN_CONTENT_TYPE_CONFIDENCE) {
+        return null;
+      }
       return bestMatch;
     }
     function getPattern(contentType) {
@@ -5432,7 +5536,7 @@ ZodNaN.create = (params) => {
     ...processCreateParams(params)
   });
 };
-var BRAND = Symbol("zod_brand");
+var BRAND = /* @__PURE__ */ Symbol("zod_brand");
 var ZodBranded = class extends ZodType {
   _parse(input) {
     const { ctx } = this._processInputParams(input);
@@ -5930,6 +6034,7 @@ async function querySupernova(resource, opts = {}) {
   const {
     designSystemId,
     versionId,
+    versionSelector,
     proxyUrl = process.env.ARBOR_MCP_SUPERNOVA_PROXY_URL ?? "",
     proxyToken = process.env.ARBOR_MCP_SUPERNOVA_PROXY_TOKEN ?? "",
     fetchImpl = globalThis.fetch,
@@ -5948,12 +6053,13 @@ async function querySupernova(resource, opts = {}) {
   if (parsed.protocol !== "https:") {
     return { ok: false, reason: "not_configured", detail: `proxy URL must be https (got ${parsed.protocol})` };
   }
-  const cacheKey = `${resource}|${designSystemId ?? ""}|${versionId ?? ""}`;
+  const cacheKey = `${resource}|${designSystemId ?? ""}|${versionId ?? ""}|${versionSelector ?? ""}`;
   const cached = cache.get(cacheKey);
   if (cached && now() - cached.fetchedAt < CACHE_TTL_MS2) return cached.value;
   const body = { resource };
   if (designSystemId) body.designSystemId = designSystemId;
   if (versionId) body.versionId = versionId;
+  if (versionSelector && !versionId) body.versionSelector = versionSelector;
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
   let res;
@@ -5998,15 +6104,124 @@ async function querySupernova(resource, opts = {}) {
   return value;
 }
 
+// src/lib/resolve-version.ts
+function extractVersionList(data) {
+  const wrapped = data?.result?.designSystemVersions;
+  const list = Array.isArray(wrapped) ? wrapped : Array.isArray(data) ? data : null;
+  if (list === null) return null;
+  return list.filter((x) => !!x && typeof x === "object");
+}
+async function resolveVersionId(version, deps = {}) {
+  const query = deps.query ?? ((r) => querySupernova(r));
+  const result = await query("versions");
+  if (!result.ok) {
+    return { ok: false, reason: "unavailable", detail: `could not load versions (${result.reason})` };
+  }
+  const list = extractVersionList(result.data);
+  if (list === null) {
+    return { ok: false, reason: "unavailable", detail: "proxy returned an unrecognized versions payload" };
+  }
+  const match = list.find((v) => v.isReadonly === true && v.version === version);
+  if (!match) {
+    return { ok: false, reason: "not_found", detail: `no frozen Supernova version "${version}" \u2014 it may not be cut yet (see arbor_list_versions)` };
+  }
+  const versionId = String(match.id ?? "");
+  if (!versionId) {
+    return { ok: false, reason: "unavailable", detail: `frozen version "${version}" has no id` };
+  }
+  const meta = match.meta;
+  const versionName = meta && typeof meta === "object" && typeof meta.name === "string" && meta.name.length > 0 ? meta.name : version;
+  return { ok: true, versionId, versionName };
+}
+
+// src/lib/intentions.ts
+var INTENTIONS_ARTIFACT = "component-intentions.json";
+var INTENTION_STATUSES = [
+  "shipped",
+  "in-progress",
+  "design-only",
+  "deprecated",
+  "researched-not-shipped"
+];
+var STATUS_SET = new Set(INTENTION_STATUSES);
+function normalizeComponentKey(name) {
+  return name.toLowerCase().replace(/[^a-z0-9]/g, "");
+}
+function asStringArray(v) {
+  return Array.isArray(v) ? v.filter((s) => typeof s === "string") : [];
+}
+function asDisambiguations(v) {
+  if (!Array.isArray(v)) return [];
+  const out = [];
+  for (const d of v) {
+    if (d && typeof d === "object") {
+      const component = d.component;
+      const distinction = d.distinction;
+      if (typeof component === "string" && typeof distinction === "string") {
+        out.push({ component, distinction });
+      }
+    }
+  }
+  return out;
+}
+function coerceEntry(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const r = raw;
+  const name = typeof r.name === "string" ? r.name.trim() : "";
+  const status = typeof r.status === "string" ? r.status : "";
+  if (!name || !STATUS_SET.has(status)) return null;
+  return {
+    name,
+    status,
+    shippedVersion: typeof r.shippedVersion === "string" ? r.shippedVersion : null,
+    useWhen: asStringArray(r.useWhen),
+    notWhen: asStringArray(r.notWhen),
+    disambiguateFrom: asDisambiguations(r.disambiguateFrom),
+    guideline: typeof r.guideline === "string" ? r.guideline : null,
+    decisions: asStringArray(r.decisions)
+  };
+}
+async function loadIntentions(load = loadPublishedJson) {
+  const res = await load(INTENTIONS_ARTIFACT);
+  if (!res.ok) return { ok: false, reason: res.reason };
+  const data = res.data;
+  if (data.degraded === true || !Array.isArray(data.components)) {
+    return { ok: false, reason: "degraded" };
+  }
+  const byKey = /* @__PURE__ */ new Map();
+  for (const raw of data.components) {
+    const entry = coerceEntry(raw);
+    if (entry) byKey.set(normalizeComponentKey(entry.name), entry);
+  }
+  return { ok: true, byKey, generatedAt: typeof data.generatedAt === "string" ? data.generatedAt : null };
+}
+
 // src/tools/list-components.ts
 var TOOL_NAME3 = "arbor_list_components";
 var TOOL_TITLE3 = "List Arbor components";
 var TOOL_DESCRIPTION3 = "List the components in the Arbor design system (name, id, short description) from Supernova via the Arbor federation proxy. Read-only metadata for discovery; returns top-level components, not Figma variants. Does NOT return token values, source code, or props \u2014 use arbor_get_component for one component, the shadcn registry/Storybook for source, arbor_open_in_playroom for a runnable snippet. Does NOT change anything.";
-var inputSchema3 = external_exports.object({ query: external_exports.string().trim().min(1).max(100).optional().describe("Optional case-insensitive name/description filter") }).strict();
+var inputSchema3 = external_exports.object({
+  query: external_exports.string().trim().min(1).max(100).optional().describe("Optional case-insensitive name/description filter"),
+  versionSelector: external_exports.enum(["draft", "latest_released"]).optional().describe(
+    "Which design system version to read: 'draft' (default \u2014 the editable working version) or 'latest_released' (the newest frozen release; available only once a release has been cut, otherwise unavailable)"
+  ),
+  version: external_exports.string().trim().min(1).max(50).optional().describe(
+    'List components as of a specific released version, e.g. "15.1.0" \u2014 resolves to that frozen Supernova version ("what shipped in 15.1.0"). Takes precedence over versionSelector. See arbor_list_versions for the versions that have been cut.'
+  )
+}).strict();
 var outputSchema3 = external_exports.object({
   source: external_exports.enum(["remote", "unavailable"]),
   total: external_exports.number(),
-  components: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), description: external_exports.string().nullable() })),
+  components: external_exports.array(
+    external_exports.object({
+      id: external_exports.string(),
+      name: external_exports.string(),
+      description: external_exports.string().nullable(),
+      // Lifecycle status merged from the component-intentions manifest (DNG-726).
+      // null when the manifest has no entry for this component or could not be loaded.
+      status: external_exports.enum(INTENTION_STATUSES).nullable()
+    })
+  ),
   detail: external_exports.string().nullable()
 });
 var annotations3 = { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false };
@@ -6025,8 +6240,23 @@ function extractComponents(data) {
   });
 }
 async function handleListComponents(args, deps = {}) {
-  const query = deps.query ?? ((r) => querySupernova(r));
-  const result = await query("components");
+  const query = deps.query ?? ((r, opts) => querySupernova(r, opts));
+  let queryOpts;
+  if (args.version) {
+    const resolveVersion = deps.resolveVersion ?? ((v) => resolveVersionId(v));
+    const resolved = await resolveVersion(args.version);
+    if (!resolved.ok) {
+      const out2 = { source: "unavailable", total: 0, components: [], detail: resolved.detail };
+      return {
+        content: [{ type: "text", text: `Could not read version ${args.version}: ${resolved.detail}. Treat as unavailable \u2014 do not assume there are none.` }],
+        structuredContent: out2
+      };
+    }
+    queryOpts = { versionId: resolved.versionId };
+  } else {
+    queryOpts = { versionSelector: args.versionSelector };
+  }
+  const result = await query("components", queryOpts);
   let out;
   const extracted = result.ok ? extractComponents(result.data) : null;
   if (!result.ok) {
@@ -6041,7 +6271,13 @@ async function handleListComponents(args, deps = {}) {
         (c) => c.name.toLowerCase().includes(q) || (c.description ? c.description.toLowerCase().includes(q) : false)
       );
     }
-    out = { source: "remote", total: components.length, components, detail: null };
+    const intentionsRes = await (deps.loadIntentions ?? (() => loadIntentions()))();
+    const byKey = intentionsRes.ok ? intentionsRes.byKey : null;
+    const withStatus = components.map((c) => ({
+      ...c,
+      status: byKey ? byKey.get(normalizeComponentKey(c.name))?.status ?? null : null
+    }));
+    out = { source: "remote", total: withStatus.length, components: withStatus, detail: null };
   }
   const summary = out.source === "unavailable" ? `Could not load components (${out.detail}). Treat as unavailable \u2014 do not assume there are none.` : `${out.total} component${out.total === 1 ? "" : "s"}${args.query ? ` matching "${args.query}"` : ""}.`;
   return { content: [{ type: "text", text: summary }], structuredContent: out };
@@ -6055,43 +6291,125 @@ var listComponentsTool = {
 // src/tools/get-component.ts
 var TOOL_NAME4 = "arbor_get_component";
 var TOOL_TITLE4 = "Get one Arbor component";
-var TOOL_DESCRIPTION4 = "Get a single Arbor component's metadata by name (case-insensitive) or id from Supernova via the Arbor federation proxy (name, id, description). Read-only; matches top-level components, not Figma variants. Does NOT return token values or rendered source \u2014 use the shadcn registry / Storybook for implementation and arbor_open_in_playroom for a runnable snippet. Does NOT change anything.";
+var TOOL_DESCRIPTION4 = "Get a single Arbor component's metadata by name (case-insensitive) or id (name, id, description) PLUS its intention overlay \u2014 lifecycle status (shipped | in-progress | design-only | deprecated | researched-not-shipped), when to use it, when NOT to (and what to use instead), and what it is commonly confused with. Intention comes from Arbor's source of truth, so a design-only component absent from the live design data still resolves. Read-only; matches top-level components, not Figma variants. Does NOT return token values or rendered source \u2014 use the shadcn registry / Storybook for implementation and arbor_open_in_playroom for a runnable snippet. Does NOT change anything.";
 var inputSchema4 = external_exports.object({
   name: external_exports.string().trim().min(1).max(100).optional().describe('Component name (case-insensitive), e.g. "Button"'),
-  id: external_exports.string().trim().min(1).max(100).optional().describe("Supernova component id")
+  id: external_exports.string().trim().min(1).max(100).optional().describe("Supernova component id"),
+  versionSelector: external_exports.enum(["draft", "latest_released"]).optional().describe(
+    "Which design system version to read: 'draft' (default \u2014 the editable working version) or 'latest_released' (the newest frozen release; available only once a release has been cut, otherwise unavailable)"
+  ),
+  version: external_exports.string().trim().min(1).max(50).optional().describe(
+    'Read a specific released version, e.g. "15.1.0" \u2014 resolves to that frozen Supernova version and reads the component there ("what shipped in 15.1.0"). Takes precedence over versionSelector. See arbor_list_versions for the versions that have been cut.'
+  )
 }).strict();
+var disambiguationSchema = external_exports.object({
+  component: external_exports.string().describe("The thing to disambiguate from \u2014 an Arbor component or an external concept (chip, snackbar, \u2026)"),
+  distinction: external_exports.string().describe("How they differ and which to pick when")
+});
+var intentionSchema = external_exports.object({
+  status: external_exports.enum(["shipped", "in-progress", "design-only", "deprecated", "researched-not-shipped"]).describe("Lifecycle/availability in the @linktr.ee/arbor package"),
+  shippedVersion: external_exports.string().nullable().describe("The arbor version where this became available, when known"),
+  useWhen: external_exports.array(external_exports.string()).describe("Situations this is the right choice for"),
+  notWhen: external_exports.array(external_exports.string()).describe("When NOT to reach for it, ideally naming the better alternative"),
+  disambiguateFrom: external_exports.array(disambiguationSchema).describe("Things this is commonly confused with"),
+  guideline: external_exports.string().nullable().describe("Repo-relative path to the long-form guideline, when one exists"),
+  decisions: external_exports.array(external_exports.string()).describe("Decision-log ids (DL-NN) that explain this intention")
+});
 var outputSchema4 = external_exports.object({
-  source: external_exports.enum(["remote", "unavailable"]),
-  found: external_exports.boolean(),
+  source: external_exports.enum(["remote", "unavailable"]).describe("Live design-data (Supernova) availability"),
+  found: external_exports.boolean().describe("True when a component OR an intention entry matched"),
   component: external_exports.object({ id: external_exports.string(), name: external_exports.string(), description: external_exports.string().nullable() }).nullable(),
+  intention: intentionSchema.nullable().describe("Intention overlay from the source-of-truth manifest; null when no entry matched or it could not be loaded"),
+  intentionSource: external_exports.enum(["remote", "absent", "unavailable"]).describe("'remote' = matched, 'absent' = manifest loaded but no entry, 'unavailable' = manifest could not be loaded"),
   detail: external_exports.string().nullable()
 });
 var annotations4 = { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false };
+async function resolveIntention(lookupName, load) {
+  const res = await load();
+  if (!res.ok) return { intention: null, intentionSource: "unavailable" };
+  if (!lookupName) return { intention: null, intentionSource: "absent" };
+  const match = res.byKey.get(normalizeComponentKey(lookupName));
+  if (!match) return { intention: null, intentionSource: "absent" };
+  const intention = {
+    status: match.status,
+    shippedVersion: match.shippedVersion,
+    useWhen: match.useWhen,
+    notWhen: match.notWhen,
+    disambiguateFrom: match.disambiguateFrom.map((d) => ({ component: d.component, distinction: d.distinction })),
+    guideline: match.guideline,
+    decisions: match.decisions
+  };
+  return { intention, intentionSource: "remote" };
+}
 async function handleGetComponent(args, deps = {}) {
   const name = args.name?.trim();
   const id = args.id?.trim();
+  const loadIntentionsFn = deps.loadIntentions ?? (() => loadIntentions());
   if (!name && !id) {
-    const out2 = { source: "remote", found: false, component: null, detail: "provide name or id" };
+    const out2 = {
+      source: "remote",
+      found: false,
+      component: null,
+      intention: null,
+      intentionSource: "absent",
+      detail: "provide name or id"
+    };
     return {
       content: [{ type: "text", text: 'Provide a component name or id \u2014 e.g. {"name":"Button"} or {"id":"35988997"}.' }],
       structuredContent: out2
     };
   }
-  const query = deps.query ?? ((r) => querySupernova(r));
-  const result = await query("components");
-  let out;
-  if (!result.ok) {
-    out = { source: "unavailable", found: false, component: null, detail: `could not load components (${result.reason})` };
+  const query = deps.query ?? ((r, opts) => querySupernova(r, opts));
+  let supernovaSource = "remote";
+  let component = null;
+  let supernovaDetail = null;
+  let queryOpts = null;
+  if (args.version) {
+    const resolveVersion = deps.resolveVersion ?? ((v) => resolveVersionId(v));
+    const resolved = await resolveVersion(args.version);
+    if (resolved.ok) {
+      queryOpts = { versionId: resolved.versionId };
+    } else {
+      supernovaSource = "unavailable";
+      supernovaDetail = resolved.detail;
+    }
   } else {
-    const components = extractComponents(result.data);
-    if (components === null) {
-      out = { source: "unavailable", found: false, component: null, detail: "proxy returned an unrecognized components payload" };
+    queryOpts = { versionSelector: args.versionSelector };
+  }
+  if (queryOpts) {
+    const result = await query("components", queryOpts);
+    if (!result.ok) {
+      supernovaSource = "unavailable";
+      supernovaDetail = `could not load components (${result.reason})`;
     } else {
-      const match = id ? components.find((c) => c.id === id) : components.find((c) => c.name.toLowerCase() === name.toLowerCase());
-      out = match ? { source: "remote", found: true, component: match, detail: null } : { source: "remote", found: false, component: null, detail: `no component ${id ? `with id ${id}` : `named "${name}"`}` };
+      const components = extractComponents(result.data);
+      if (components === null) {
+        supernovaSource = "unavailable";
+        supernovaDetail = "proxy returned an unrecognized components payload";
+      } else {
+        const target = name ? normalizeComponentKey(name) : null;
+        const match = id ? components.find((c) => c.id === id) : components.find((c) => normalizeComponentKey(c.name) === target);
+        if (match) component = match;
+        else supernovaDetail = `no component ${id ? `with id ${id}` : `named "${name}"`}`;
+      }
     }
   }
-  const summary = out.source === "unavailable" ? `Could not load components (${out.detail}). Treat as unavailable.` : out.found ? `${out.component.name}${out.component.description ? ` \u2014 ${out.component.description}` : " (no description)"}.` : `No Arbor component ${args.id ? `with id ${args.id.trim()}` : `named "${args.name?.trim()}"`} exists.`;
+  const lookupName = component?.name ?? name ?? null;
+  const { intention, intentionSource } = await resolveIntention(lookupName, loadIntentionsFn);
+  const found = component !== null || intention !== null;
+  let detail = supernovaDetail;
+  if (!component && intention) {
+    detail = supernovaSource === "unavailable" ? `live design data unavailable (${supernovaDetail}); intention found \u2014 status "${intention.status}"` : `not in the live design data, but tracked as "${intention.status}" in Arbor's component intentions`;
+  }
+  const out = { source: supernovaSource, found, component, intention, intentionSource, detail };
+  let summary;
+  if (!found) {
+    summary = supernovaSource === "unavailable" ? `Could not load components (${supernovaDetail}). Treat as unavailable.` : `No Arbor component ${id ? `with id ${id}` : `named "${name}"`} exists.`;
+  } else {
+    const head = component ? `${component.name}${component.description ? ` \u2014 ${component.description}` : " (no description)"}.` : `${lookupName} \u2014 ${detail}.`;
+    const intentionLine = intention ? ` Status: ${intention.status}.${intention.useWhen.length ? ` Use when: ${intention.useWhen[0]}` : ""}` : intentionSource === "unavailable" ? " (intention overlay unavailable)" : "";
+    summary = `${head}${intentionLine}`;
+  }
   return { content: [{ type: "text", text: summary }], structuredContent: out };
 }
 var getComponentTool = {
@@ -6103,15 +6421,38 @@ var getComponentTool = {
 // src/tools/list-versions.ts
 var TOOL_NAME5 = "arbor_list_versions";
 var TOOL_TITLE5 = "List Arbor design system versions";
-var TOOL_DESCRIPTION5 = "List the version history of the Arbor design system (id, name, created date, read-only flag) from Supernova via the Arbor federation proxy. Read-only metadata. Does NOT return token values (use the compiled CSS / registry) and does NOT change anything.";
+var TOOL_DESCRIPTION5 = "List the version history of the Arbor design system from Supernova (id, name, semver, created date, read-only flag, draft / latest-released markers) via the Arbor federation proxy, plus the committed release manifest (npm release \u2194 Supernova version). Read-only metadata. Does NOT return token values (use the compiled CSS / registry) and does NOT change anything.";
 var inputSchema5 = external_exports.object({}).strict();
+var versionSchema = external_exports.object({
+  id: external_exports.string(),
+  name: external_exports.string(),
+  semver: external_exports.string().nullable().describe('The version string when it parses as semver (X.Y.Z); null for the draft, whose version is a label like "Shared Draft"'),
+  createdAt: external_exports.string().nullable(),
+  readOnly: external_exports.boolean().nullable(),
+  isDraft: external_exports.boolean().nullable().describe("The editable working version (readOnly === false). DNG-594: a draft's version is a label, not null \u2014 so readOnly is the signal."),
+  isLatestReleased: external_exports.boolean().describe("True for the single newest read-only (frozen) version by createdAt")
+});
+var manifestReleaseSchema = external_exports.object({
+  releaseId: external_exports.string(),
+  date: external_exports.string().nullable(),
+  frontDoorVersion: external_exports.string().nullable().describe("The @linktr.ee/arbor version for this release (DL-076 front-door number)"),
+  supernovaVersionId: external_exports.string().nullable().describe("The frozen Supernova version id this release was cut as (null until the cutter + stamper run \u2014 later phases)"),
+  supernovaStatus: external_exports.string().nullable()
+});
 var outputSchema5 = external_exports.object({
-  source: external_exports.enum(["remote", "unavailable"]).describe("'remote' = fetched; 'unavailable' = proxy fetch failed"),
-  total: external_exports.number().describe("Number of versions returned"),
-  versions: external_exports.array(external_exports.object({ id: external_exports.string(), name: external_exports.string(), createdAt: external_exports.string().nullable(), readOnly: external_exports.boolean().nullable() })).describe("Versions, in the order Supernova returned them"),
+  source: external_exports.enum(["remote", "unavailable"]).describe("'remote' = Supernova versions fetched; 'unavailable' = proxy fetch failed"),
+  total: external_exports.number().describe("Number of Supernova versions returned"),
+  versions: external_exports.array(versionSchema).describe("Supernova versions, in the order returned"),
+  manifest: external_exports.object({
+    source: external_exports.enum(["local", "unavailable"]).describe("'local' = release manifest loaded; 'unavailable' = not published yet / degraded"),
+    total: external_exports.number(),
+    releases: external_exports.array(manifestReleaseSchema),
+    detail: external_exports.string().nullable()
+  }).describe("The committed release manifest (releases.json) mapping npm releases \u2194 Supernova versions"),
   detail: external_exports.string().nullable().describe("Degraded reason when source is unavailable")
 });
 var annotations5 = { readOnlyHint: true, idempotentHint: true, openWorldHint: true, destructiveHint: false };
+var SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+].*)?$/;
 function extractList(data) {
   const wrapped = data?.result?.designSystemVersions;
   const list = Array.isArray(wrapped) ? wrapped : Array.isArray(data) ? data : null;
@@ -6119,26 +6460,86 @@ function extractList(data) {
   return list.filter((x) => !!x && typeof x === "object");
 }
 var str2 = (v) => typeof v === "string" && v.length > 0 ? v : null;
+var semverOf = (v) => {
+  const s = str2(v);
+  return s && SEMVER_RE.test(s) ? s : null;
+};
+var createdAtEpoch = (s) => {
+  const t = new Date(s ?? 0).getTime();
+  return Number.isFinite(t) ? t : 0;
+};
+var metaName = (v) => {
+  const meta = v.meta;
+  return meta && typeof meta === "object" ? str2(meta.name) : null;
+};
+function latestReleasedId(versions) {
+  const frozen = versions.filter((v) => v.readOnly === true);
+  if (frozen.length === 0) return null;
+  frozen.sort((a, b) => createdAtEpoch(b.createdAt) - createdAtEpoch(a.createdAt));
+  return frozen[0].id || null;
+}
+async function buildManifestLane(load) {
+  const res = await load("releases.json");
+  if (!res.ok) {
+    return { source: "unavailable", total: 0, releases: [], detail: `could not load release manifest (${res.reason})` };
+  }
+  const data = res.data;
+  if (data?.degraded === true) {
+    return { source: "unavailable", total: 0, releases: [], detail: "release manifest is a degraded fallback" };
+  }
+  if (!data || !Array.isArray(data.releases)) {
+    return { source: "unavailable", total: 0, releases: [], detail: "unrecognized releases.json payload" };
+  }
+  const releases = data.releases.filter((r) => !!r && typeof r === "object").map((r) => {
+    const sn = r.supernova ?? {};
+    return {
+      releaseId: String(r.releaseId ?? ""),
+      date: str2(r.date),
+      frontDoorVersion: str2(r.frontDoorVersion),
+      supernovaVersionId: str2(sn.versionId),
+      supernovaStatus: str2(sn.status)
+    };
+  });
+  return { source: "local", total: releases.length, releases, detail: null };
+}
 async function handleListVersions(_args, deps = {}) {
   const query = deps.query ?? ((r) => querySupernova(r));
+  const load = deps.load ?? ((f) => loadPublishedJson(f));
   const result = await query("versions");
-  let out;
   const list = result.ok ? extractList(result.data) : null;
+  let source;
+  let versions;
+  let detail;
   if (!result.ok) {
-    out = { source: "unavailable", total: 0, versions: [], detail: `could not load versions (${result.reason})` };
+    source = "unavailable";
+    versions = [];
+    detail = `could not load versions (${result.reason})`;
   } else if (list === null) {
-    out = { source: "unavailable", total: 0, versions: [], detail: "proxy returned an unrecognized versions payload" };
+    source = "unavailable";
+    versions = [];
+    detail = "proxy returned an unrecognized versions payload";
   } else {
-    const versions = list.map((v) => ({
+    const base = list.map((v) => ({
       id: String(v.id ?? ""),
-      name: str2(v.version) ?? str2(v.name) ?? "(unnamed)",
+      name: metaName(v) ?? str2(v.version) ?? "(unnamed)",
+      semver: semverOf(v.version),
       createdAt: str2(v.createdAt),
       readOnly: typeof v.isReadonly === "boolean" ? v.isReadonly : null
     }));
-    out = { source: "remote", total: versions.length, versions, detail: null };
-  }
-  const summary = out.source === "unavailable" ? `Could not load design system versions (${out.detail}). Treat as unavailable \u2014 do not assume there are none.` : `${out.total} design system version${out.total === 1 ? "" : "s"}: ${out.versions.map((v) => v.name).join(", ") || "(none)"}.`;
-  return { content: [{ type: "text", text: summary }], structuredContent: out };
+    const latest = latestReleasedId(base);
+    versions = base.map((v) => ({
+      ...v,
+      isDraft: v.readOnly === null ? null : v.readOnly === false,
+      isLatestReleased: latest !== null && v.id === latest
+    }));
+    source = "remote";
+    detail = null;
+  }
+  const manifest = await buildManifestLane(load);
+  const out = { source, total: versions.length, versions, manifest, detail };
+  const versionsLine = out.source === "unavailable" ? `Supernova versions unavailable (${out.detail}) \u2014 do not assume there are none.` : `${out.total} Supernova version${out.total === 1 ? "" : "s"}: ${out.versions.map((v) => v.name).join(", ") || "(none)"}.`;
+  const manifestLine = manifest.source === "unavailable" ? `Release manifest unavailable (${manifest.detail}).` : `${manifest.total} manifest release${manifest.total === 1 ? "" : "s"} (front-door: ${manifest.releases.map((r) => r.frontDoorVersion).filter(Boolean).join(", ") || "n/a"}).`;
+  return { content: [{ type: "text", text: `${versionsLine} ${manifestLine}` }], structuredContent: out };
 }
 var listVersionsTool = {
   name: TOOL_NAME5,
@@ -6918,6 +7319,30 @@ var compositions_default = [
     code: `<RadioGroup defaultValue="option-1">
   <RadioButton value="option-1" variant="pill">Option 1</RadioButton>
   <RadioButton value="option-2" variant="pill">Option 2</RadioButton>
+</RadioGroup>`
+  },
+  // ── Radio ──
+  // Maps to figma-mappings `Radio` (canonical control, node 9232-27291). The bare
+  // 20px control must render inside a RadioGroup; pair each with an accessible
+  // name (aria-label here, or a sibling <label htmlFor> in real usage).
+  {
+    group: "Radio",
+    name: "Radio",
+    code: `<RadioGroup defaultValue="email" aria-label="Notifications">
+  <Radio value="email" aria-label="Email" />
+  <Radio value="sms" aria-label="SMS" />
+  <Radio value="push" aria-label="Push notification" />
+</RadioGroup>`
+  },
+  // ── RadioItem ──
+  // Maps to figma-mappings `RadioItem` (canonical control + label, node 12360-58265).
+  {
+    group: "RadioItem",
+    name: "RadioItem",
+    code: `<RadioGroup defaultValue="email" aria-label="Notifications">
+  <RadioItem value="email" description="We'll send a confirmation">Email</RadioItem>
+  <RadioItem value="sms">SMS</RadioItem>
+  <RadioItem value="push" disabled>Push notification</RadioItem>
 </RadioGroup>`
   },
   // ── SearchInput ──

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@linktr.ee/arbor-mcp",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Model Context Protocol server exposing Arbor design system tools: Playroom snippets, Figma→code sync health, UX-writing checks, decision-log lookup, and federated component/version metadata.",
   "keywords": [
     "arbor",
@@ -45,7 +45,7 @@
     "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "devDependencies": {
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.28.1",
     "tsx": "^4.7.0",
     "typescript": "^5.7.0",
     "zod": "3.25.76"