@adia-ai/mcp 0.8.37 → 0.8.39

package/factory/vendor/record-lint

@@ -0,0 +1,278 @@
+#!/usr/bin/env python3
+"""record-lint — mechanical gate for app-planning's Orientation Record.
+
+The record is app-planning's typed deliverable (SKILL.md §The Orientation
+Record) and the app-planning-agent → screen-composition-agent handoff artifact. Until
+this linter existed, nothing checked a record's shape — and the record's
+three in-tree consumers had already drifted from the contract (the
+factory-audit finding this closes, gh#259 Wave 2).
+
+Checks (the contract's mechanizable slice — shape, enums, evidence,
+route-legality; whether a SIGNAL is genuinely load-bearing stays the
+model's judgment):
+  1. Required lines present: Rendering mode / Project shape / Shell /
+     Task / → Route / Verify target / Open questions. Screen plan is
+     conditional (start mode) — its absence is never an error.
+  2. Axis enums: mode ∈ {SPA, SSR, hybrid} · shape ∈ {single-surface,
+     rollup, shared-foundation} · shell ∈ {admin, chat, editor, simple,
+     embed, none}.
+  3. Every axis line carries a non-empty `— signal:` clause that isn't a
+     bare restatement of the value.
+  4. Route names only skills that exist in this plugin (the task table's
+     roster), or app-planning itself.
+  5. Every Open-questions entry names its fallback (`fallback:`).
+  6. Verify target non-empty and not TBD-ish.
+  7. Domain Plan (gh#1207, REQ-02) — CONDITIONAL: absent is never an
+     error (spec-shaped input only, mirrors Screen plan's conditionality).
+     When a `## Domain Plan` heading IS present, its required sub-fields
+     (Intent / Domain / Roles / Tasks / Decisions / Wireframe) must each
+     appear non-empty, and Wireframe must name a checkpoint verdict
+     (PASSED or FAILED).
+
+Usage:
+  record-lint <file>       # lint a file containing a record
+  record-lint -            # lint stdin
+  record-lint selftest     # embedded fixtures; exit 0 iff all pass
+Exit 1 on findings, 0 clean. Stdlib only (Python 3.8+).
+"""
+import re
+import sys
+
+AXES = {
+    'Rendering mode': {'SPA', 'SSR', 'hybrid'},
+    'Project shape': {'single-surface', 'rollup', 'shared-foundation'},
+    'Shell': {'admin', 'chat', 'editor', 'simple', 'embed', 'none'},
+}
+REQUIRED = ['Rendering mode', 'Project shape', 'Shell', 'Task', '→ Route', 'Verify target', 'Open questions']
+ROUTE_SKILLS = {
+    'app-planning', 'project-scaffolding', 'screen-composition', 'shell-selection', 'host-wiring',
+    'data-wiring', 'llm-wiring', 'gen-ui-wiring', 'surface-qa', 'app-migration',
+}
+TBD_RE = re.compile(r'^\s*(tbd|todo|\?+|—|-)\s*$', re.I)
+
+# gh#1207 REQ-02 — the Orientation Record's CONDITIONAL Domain Plan block
+# (spec-shaped input only; app-planning SKILL.md §The Orientation Record).
+# Shape (sketch: .claude/docs/specs/factory-roster-completion.md):
+#   ## Domain Plan (rungs 0–19, ladder vX)
+#   - Intent: ... - Domain: ... - Roles: ... - Tasks: ... - Decisions: ...
+#   - Wireframe: ... checkpoint PASSED|FAILED
+DOMAIN_PLAN_HEADING_RE = re.compile(r'^##\s*Domain Plan\b.*$', re.M)
+DOMAIN_PLAN_FIELDS = ['Intent', 'Domain', 'Roles', 'Tasks', 'Decisions', 'Wireframe']
+DOMAIN_PLAN_FIELD_RE = re.compile(
+    r'-\s*(' + '|'.join(DOMAIN_PLAN_FIELDS) + r')\s*:[ \t]*(.*?)'
+    r'(?=(?:[ \t]+-\s*(?:' + '|'.join(DOMAIN_PLAN_FIELDS) + r')\s*:)|\n|$)'
+)
+
+
+def lint(text):
+    findings = []
+    lines = {}
+    for raw in text.splitlines():
+        m = re.match(r'^\s*(→ Route|[A-Z][\w ]+?):\s*(.*)$', raw)
+        if m:
+            lines.setdefault(m.group(1).strip(), []).append(m.group(2).strip())
+
+    for label in REQUIRED:
+        if label not in lines:
+            findings.append(f"missing line: '{label}:'")
+
+    for axis, enum in AXES.items():
+        for value in lines.get(axis, []):
+            head = value.split('—')[0].strip()
+            sig = re.search(r'—\s*signal:\s*(.*)$', value)
+            if head not in enum:
+                findings.append(f"{axis}: '{head}' not in {sorted(enum)}")
+            if not sig or not sig.group(1).strip():
+                findings.append(f"{axis}: no '— signal:' clause (Evidence gate)")
+            elif head and head.lower() in sig.group(1).strip().lower() and len(sig.group(1).strip()) <= len(head) + 12:
+                findings.append(f"{axis}: signal restates the value ('{sig.group(1).strip()}')")
+
+    for value in lines.get('→ Route', []):
+        # kebab tokens that are either current factory skills or legacy
+        # adia-* names (the latter flag as not-a-factory-skill below, so an
+        # un-migrated record fails loudly instead of passing silently)
+        tokens = set(re.findall(r'[a-z][a-z0-9-]*[a-z0-9]', value))
+        named = {t for t in tokens if t in ROUTE_SKILLS or t.startswith('adia-')}
+        for skill in named - ROUTE_SKILLS:
+            findings.append(f"Route: '{skill}' is not a factory skill (Route-legal gate)")
+        if not named:
+            findings.append("Route: names no skill")
+
+    for value in lines.get('Verify target', []):
+        if not value or TBD_RE.match(value):
+            findings.append("Verify target: empty or TBD")
+
+    for value in lines.get('Open questions', []):
+        if value and not TBD_RE.match(value) and value.lower() not in ('none', 'blank if none', ''):
+            if 'fallback' not in value.lower():
+                findings.append(f"Open questions: entry lacks a named fallback: '{value[:50]}'")
+
+    findings.extend(_lint_domain_plan(text))
+    return findings
+
+
+def _lint_domain_plan(text):
+    """gh#1207 REQ-02 — conditional Domain Plan block. Absence is never a
+    finding (never required); presence gates its own required sub-fields."""
+    heading = DOMAIN_PLAN_HEADING_RE.search(text)
+    if not heading:
+        return []
+    start = heading.end()
+    next_heading = re.search(r'\n##\s', text[start:])
+    block = text[start:start + next_heading.start()] if next_heading else text[start:]
+
+    found = {}
+    for fm in DOMAIN_PLAN_FIELD_RE.finditer(block):
+        found.setdefault(fm.group(1), fm.group(2).strip())
+
+    findings = []
+    for field in DOMAIN_PLAN_FIELDS:
+        if field not in found:
+            findings.append(f"Domain Plan: missing '{field}:' field")
+        elif not found[field]:
+            findings.append(f"Domain Plan: '{field}:' is empty")
+
+    wireframe = found.get('Wireframe', '')
+    if wireframe and not re.search(r'\b(PASSED|FAILED)\b', wireframe, re.I):
+        findings.append("Domain Plan: 'Wireframe:' names no checkpoint verdict (PASSED/FAILED)")
+
+    return findings
+
+
+GOOD = """\
+Rendering mode:  SPA — signal: no framework dep in package.json; index.html present
+Project shape:   single-surface — signal: one entry under app/claims/
+Shell:           admin — signal: sidebar + topbar + command palette in the brief
+Task:            build a claims-review screen — signal: the request
+Screen plan:     1. Claims list — reviewer scans and opens a claim
+→ Route:         project-scaffolding, screen-composition, in order per the task table
+Verify target:   composed screen renders; adia-lint clean; browser gate
+Open questions:  auth model unclear — fallback: mock session until the API lands
+"""
+
+BAD = """\
+Rendering mode:  Static — signal: SPA
+Shell:           admin
+→ Route:         adia-scaffolding
+Verify target:   TBD
+Open questions:  auth model unclear
+"""
+
+# gh#1207 REQ-02 — GOOD_WITH_DOMAIN_PLAN proves a spec-shaped record with a
+# complete, well-formed Domain Plan block stays clean (the block is
+# conditional, never required — GOOD above already proves a plain record
+# with NO block is clean). Uses the spec sketch's own compressed
+# "field: value    - field: value" line shape for Roles/Tasks to prove the
+# parser handles it, not just one-field-per-line.
+GOOD_WITH_DOMAIN_PLAN = GOOD + """
+## Domain Plan (rungs 0–19, ladder v1)
+- Intent: reviewers triage claims fast · cut time-to-resolution
+- Domain: claim, adjuster, SLA · open-claims-count, avg-resolution-hours
+- Roles: adjuster, supervisor           - Tasks: triage queue · escalate stuck claims
+- Decisions: assign / escalate / close, on priority + SLA risk
+- Wireframe: sidebar + queue + drawer, D1-D6 all ≥ 3, checkpoint PASSED
+"""
+
+# BAD_DOMAIN_PLAN: axis lines are fine (reuses GOOD) but the Domain Plan
+# block is missing Decisions entirely, leaves Roles empty, and never names
+# a checkpoint verdict — each must be caught independently.
+BAD_DOMAIN_PLAN = GOOD + """
+## Domain Plan (rungs 0–19, ladder v1)
+- Intent: reviewers triage claims fast · cut time-to-resolution
+- Domain: claim, adjuster, SLA · open-claims-count, avg-resolution-hours
+- Roles:
+- Tasks: triage queue · escalate stuck claims
+- Wireframe: sidebar + queue + drawer, D1-D6 all ≥ 3
+"""
+
+# gh#1215 review F1 — the spec sketch (above, "Shape") separates compressed
+# fields with a SINGLE space; the boundary lookahead must accept one-or-more
+# spaces/tabs, not two-or-more, or a sketch-faithful record falsely fails.
+GOOD_SINGLE_SPACE_PLAN = GOOD + """
+## Domain Plan (rungs 0–19, ladder v1)
+- Intent: reviewers triage claims fast - Domain: claim, adjuster, SLA - Roles: adjuster, supervisor - Tasks: triage queue - Decisions: assign / escalate, on SLA risk
+- Wireframe: sidebar + queue + drawer, checkpoint PASSED
+"""
+
+GOOD_SINGLE_TAB_PLAN = GOOD + """
+## Domain Plan (rungs 0–19, ladder v1)
+- Intent: reviewers triage claims fast	- Domain: claim, adjuster, SLA	- Roles: adjuster, supervisor	- Tasks: triage queue	- Decisions: assign / escalate, on SLA risk
+- Wireframe: sidebar + queue + drawer, checkpoint PASSED
+"""
+
+
+def _selftest():
+    import io
+
+    fails = []
+    if lint(GOOD):
+        fails.append(f"good fixture flagged: {lint(GOOD)}")
+    bad = lint(BAD)
+    expect = ['missing line', "not in", "no '— signal:'", 'not a factory skill', 'empty or TBD', 'lacks a named fallback']
+    for e in expect:
+        if not any(e in f for f in bad):
+            fails.append(f"bad fixture missed: {e} (got {bad})")
+
+    # gh#1207 REQ-02 — Domain Plan block: conditional-pass + presence-checks.
+    if lint(GOOD_WITH_DOMAIN_PLAN):
+        fails.append(f"good-with-domain-plan fixture flagged: {lint(GOOD_WITH_DOMAIN_PLAN)}")
+    # gh#1215 review F1 — single-space and single-tab compressed records
+    # (the sketch's own separator) must parse clean.
+    for name, fixture in (('single-space', GOOD_SINGLE_SPACE_PLAN), ('single-tab', GOOD_SINGLE_TAB_PLAN)):
+        got = lint(fixture)
+        if got:
+            fails.append(f'{name} compressed Domain Plan fixture flagged: {got}')
+    bad_plan = lint(BAD_DOMAIN_PLAN)
+    expect_plan = ["missing 'Decisions:'", "'Roles:' is empty", "names no checkpoint verdict"]
+    for e in expect_plan:
+        if not any(e in f for f in bad_plan):
+            fails.append(f"bad-domain-plan fixture missed: {e} (got {bad_plan})")
+
+    # REQ-05 (gh#1136): -h/--help exits 0 and prints usage — never a crash.
+    for flag in ('-h', '--help'):
+        saved_out = sys.stdout
+        sys.stdout = io.StringIO()
+        try:
+            rc_help = main(['record-lint', flag])
+            help_out = sys.stdout.getvalue()
+        finally:
+            sys.stdout = saved_out
+        if rc_help != 0:
+            fails.append(f'{flag} did not exit 0')
+        if not help_out.startswith('usage:'):
+            fails.append(f'{flag} did not print usage')
+
+    if fails:
+        print('selftest FAIL: ' + ' | '.join(fails), file=sys.stderr)
+        return 1
+    print(f'selftest OK — good fixture clean, bad fixture {len(bad)} findings, Domain Plan bad fixture {len(bad_plan)} findings, -h/--help contract holds')
+    return 0
+
+
+_USAGE = 'usage: record-lint <file>  |  record-lint -  |  record-lint selftest'
+
+
+def main(argv):
+    if len(argv) > 1 and argv[1] == 'selftest':
+        return _selftest()
+    # REQ-05 (gh#1136, factory-dx-ws5-consumer-verify): -h/--help must print
+    # usage and exit 0. Previously unhandled — `-h` fell through to the
+    # positional-file branch and crashed with an uncaught FileNotFoundError
+    # (exit 1, a traceback dumped to stderr), the gh#1122 class taken further.
+    if len(argv) > 1 and argv[1] in ('-h', '--help'):
+        print(_USAGE)
+        return 0
+    text = sys.stdin.read() if (len(argv) < 2 or argv[1] == '-') else open(argv[1], encoding='utf-8').read()
+    findings = lint(text)
+    if findings:
+        print(f'record-lint · {len(findings)} finding(s):')
+        for f in findings:
+            print(f'  {f}')
+        print('Contract: app-planning SKILL.md §The Orientation Record.')
+        return 1
+    print('record-lint · clean')
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main(sys.argv))

package/gen-ui/server.d.ts

@@ -1,7 +1,7 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
- * Builds the AdiaUI generation MCP server (30 tools: generation, discovery,
+ * Builds the AdiaUI generation MCP server (31 tools: generation, discovery,
  * retrieval, synthesis, validation, feedback/eval) with no transport
  * attached. Exported for tests and for `scripts/build/generate-mcp-tools-md.mjs`;
  * this file's own top-level `main()` call (unconditional, at module scope —

package/gen-ui/tools/corpus.js

@@ -7,7 +7,7 @@ import {
 } from "@adia-ai/gen-ui/corpus/chunk-library";
 const SEARCH_CHUNKS_DESCRIPTION = `Search the gen-UI training-chunk corpus by keyword.
 
-The chunk corpus comes from \`packages/gen-ui/corpus/chunks/\` \u2014 JSON records
+The chunk corpus comes from \`packages/gen-ui/engine/corpus/chunks/\` \u2014 JSON records
 extracted from every \`[data-chunk]\` element in site/pages/* and the corpus
 exemplars. There are three kinds:
   - block (default): atomic UI fragment (KPI grid, sign-in form, table)

package/gen-ui/tools/discovery.js

@@ -4,7 +4,89 @@ import {
   getAllCompositions
 } from "@adia-ai/gen-ui/compose/strategies/zettel/composition-library";
 import { getChunk, getChunkIndex } from "@adia-ai/gen-ui/corpus/chunk-library";
+let _tierIndex = null;
+async function loadTierIndex() {
+  if (_tierIndex) return _tierIndex;
+  const mod = await import("@adia-ai/a2ui/catalog/tiers", { with: { type: "json" } });
+  _tierIndex = mod.default ?? mod;
+  return _tierIndex;
+}
+const GET_CATALOG_TIERS_DESCRIPTION = `Enumerate the AdiaUI catalog's tier ladder (ADR-0050): L0 primitives, L1 widgets, L2 layouts, L3 shells, L4 flows. Every tier-N entry is a declared composition of tier-(N-1) entries, so \`composes\` is the ladder edge you follow to expand an entry into the rung below.
+
+Called with no arguments it returns the ladder summary \u2014 per tier: entry unit, which tier it composes, whether it is populated or still reserved, and the entry count. Pass \`tier\` to list that tier's entry names; pass \`tier\` + \`name\` for one entry's full record.
+
+This is the CONTRACT view (what exists and how it composes), served from \`@adia-ai/a2ui/catalog\`. For per-component prop schemas use \`get_component_map\` / \`lookup_component\`; for corpus fuel (harvested chunks) use \`search_chunks\`.`;
 function registerDiscoveryTools(server) {
+  server.tool(
+    "get_catalog_tiers",
+    GET_CATALOG_TIERS_DESCRIPTION,
+    {
+      tier: z.enum(["L0", "L1", "L2", "L3", "L4"]).optional().describe("List one tier's entries instead of the ladder summary"),
+      name: z.string().optional().describe("With `tier`, return this single entry's full record")
+    },
+    async ({ tier, name }) => {
+      const index = await loadTierIndex();
+      if (!tier) {
+        const ladder = Object.fromEntries(
+          Object.entries(index.tiers).map(([id, t]) => [
+            id,
+            { unit: t.unit, composesTier: t.composesTier, status: t.status, count: t.count }
+          ])
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({ catalogId: index.catalogId, ladder }, null, 2)
+            }
+          ]
+        };
+      }
+      const rung = index.tiers[tier];
+      if (!rung) {
+        return {
+          content: [{ type: "text", text: `Unknown tier "${tier}"` }],
+          isError: true
+        };
+      }
+      if (name) {
+        const entry = rung.entries[name];
+        if (!entry) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No ${tier} entry named "${name}". ${rung.count} entries in this tier.`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify({ tier, name, entry }, null, 2) }]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                tier,
+                unit: rung.unit,
+                composesTier: rung.composesTier,
+                status: rung.status,
+                count: rung.count,
+                entries: Object.keys(rung.entries).sort()
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
   server.tool(
     "list_patterns",
     `List all composition patterns in the A2UI corpus. Optional filters narrow by domain (auth, settings, dashboard, etc.) or category (block, page, flow).`,

package/gen-ui/tools/feedback.js

@@ -11,7 +11,7 @@ function registerFeedbackTools(server) {
     // TOOLS.md, which no MCP client could read. TOOLS.md is generated from here now.
     `Submit structured feedback for a generation execution. Used by the evolution engine to learn from each generation.
 
-Persists the rating to \`packages/gen-ui/corpus/feedback/<date>.jsonl\` through the shared \`submitFeedback\` path \u2014 the same one the gen-UI gallery's thumbs affordance posts to (gh#668). Optional \`engine\` / \`strategy\` / \`score\` / \`source\` context is carried onto the stored rating so human signal can rank weak domains.`,
+Persists the rating to \`packages/gen-ui/engine/corpus/feedback/<date>.jsonl\` through the shared \`submitFeedback\` path \u2014 the same one the gen-UI gallery's thumbs affordance posts to (gh#668). Optional \`engine\` / \`strategy\` / \`score\` / \`source\` context is carried onto the stored rating so human signal can rank weak domains.`,
     {
       executionId: z.string().describe("Execution ID from generate_ui"),
       rating: z.number().min(1).max(5).describe("Overall quality 1-5 (>=4 counts as a thumbs-up)"),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@adia-ai/mcp",
-  "version": "0.8.37",
-  "description": "AdiaUI's two MCP servers, one npm package (gh#1240). `adia-mcp gen-ui` — the 30-tool generation server (compose engine, corpus, retrieval, feedback/eval loop). `adia-mcp protocol` — the 4-tool A2UI protocol server (validate + registry introspection, no generation system, no model client). ADR-0048 §3's two-server decision is unchanged; only the distribution unified.",
+  "version": "0.8.39",
+  "description": "AdiaUI's three MCP servers, one npm package (gh#1240, ADR-0051). `adia-mcp gen-ui` — the 31-tool generation server (compose engine, corpus, retrieval, feedback/eval loop). `adia-mcp protocol` — the 5-tool A2UI protocol server (validate + registry introspection + the L0/L1 catalog-contract rungs, no generation system, no model client). `adia-mcp factory` — the 7-tool adia-factory server (orient, scaffold, audit, surface QA for building adia-ui apps from any MCP harness; no generation system, no model client). ADR-0048 §3's distinct-server decision is unchanged; only the distribution unified.",
   "type": "module",
   "bin": {
     "adia-mcp": "./bin/adia-mcp"
@@ -16,6 +16,11 @@
       "types": "./protocol/server.d.ts",
       "import": "./protocol/server.js",
       "default": "./protocol/server.js"
+    },
+    "./factory/server.js": {
+      "types": "./factory/server.d.ts",
+      "import": "./factory/server.js",
+      "default": "./factory/server.js"
     }
   },
   "files": [
@@ -26,6 +31,11 @@
     "gen-ui/tools/",
     "protocol/server.js",
     "protocol/tools/",
+    "factory/server.js",
+    "factory/tools/",
+    "factory/vendor/",
+    "factory/resources/",
+    "factory/public-surface.json",
     "README.md",
     "TOOLS.md",
     "CHANGELOG.md",
@@ -41,7 +51,7 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/adiahealth/gen-ui-kit.git",
-    "directory": "packages/mcp"
+    "directory": "packages/gen-ui/mcp"
   },
   "dependencies": {
     "@adia-ai/a2ui": "^0.8.0",

package/protocol/server.d.ts

@@ -1,8 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 
 /**
- * Builds the A2UI protocol MCP server (4 tools: validate_document,
- * get_registry_map, get_wiring_registry, protocol_status) with no transport
+ * Builds the A2UI protocol MCP server (5 tools: validate_document,
+ * get_registry_map, get_wiring_registry, get_catalog_ladder, protocol_status)
+ * with no transport
  * attached. Exported for tests and for `scripts/build/generate-mcp-tools-md.mjs`;
  * the module's own top-level `isEntryPoint()` guard is what actually starts a
  * stdio transport when this file is run directly (`node server.js`), not when

package/protocol/server.js

@@ -16,7 +16,7 @@ async function main() {
   const server = createServer();
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  console.error("[a2ui-protocol-mcp] stdio transport ready (4 protocol tools)");
+  console.error("[a2ui-protocol-mcp] stdio transport ready (5 protocol tools)");
 }
 function isEntryPoint() {
   if (typeof process === "undefined" || !process.argv[1]) return false;

package/protocol/tools/protocol.js

@@ -10,6 +10,11 @@ This is the registry view \u2014 the authoritative answer to "what types exist a
 const GET_WIRING_REGISTRY_DESCRIPTION = `Get the A2UI wiring registry: controller types, action-handler names, and data-URI resolver schemes the runtime can resolve.
 
 Read live from the runtime's wiringRegistry, so it cannot drift from what the renderer will actually accept. The richer authoring knowledge base (UI event payloads, refresh strategies, value sources, association types) is generation-side \u2014 see gen-ui-mcp's \`get_wiring_catalog\` tool instead.`;
+const GET_CATALOG_LADDER_DESCRIPTION = `Enumerate the AdiaUI catalog contract's served rungs: L0 primitives (component vocabulary) and L1 widgets (named, versioned, chat-scale functional units \u2014 a Row of stat cards, a sign-in card, a tool-call accordion). An L1 entry carries its A2UI \`template\`, so this is the tool to call before generating a document by hand: find the widget, take its template, fill in the copy.
+
+Called with no arguments it returns the ladder summary \u2014 every rung with its entry unit, the rung it composes, populated/reserved status, and entry count. Pass \`tier\` ("L0" or "L1") for that rung's entry names; pass \`tier\` + \`name\` for one entry's full record (\`composes\`, \`template\`, \`keywords\`, \`domain\`, provenance).
+
+Scope, per ADR-0050's serving map: this server serves **L0 + L1** \u2014 the rungs a chat agent enumerates to emit A2UI. L2 layouts, L3 shells, and L4 flows are developer-facing and belong to the factory surface; \`adia-mcp gen-ui\`'s \`get_catalog_tiers\` serves the whole ladder for retrieval. The ladder's one law is that every tier-N entry is a declared composition of tier-(N-1) entries, so \`composes\` is the edge you follow down a rung \u2014 an L1 entry's \`composes\` names L0 types you can validate with \`validate_document\`.`;
 const PROTOCOL_STATUS_DESCRIPTION = `Returns operational status of this A2UI protocol MCP server: transport and protocol-registry stats. Reports on the protocol server only \u2014 gen-ui-mcp's \`server_status\` tool reports its own corpus-side status separately.`;
 function buildRegistryView() {
   const byTag = /* @__PURE__ */ new Map();
@@ -25,6 +30,14 @@ function buildRegistryView() {
   })).sort((a, b) => a.type.localeCompare(b.type));
   return { totalTypes: registry.size, totalTags: byTag.size, entries };
 }
+const SERVED_TIERS = ["L0", "L1"];
+let _tierIndex = null;
+async function loadTierIndex() {
+  if (_tierIndex) return _tierIndex;
+  const mod = await import("@adia-ai/a2ui/catalog/tiers", { with: { type: "json" } });
+  _tierIndex = mod.default ?? mod;
+  return _tierIndex;
+}
 function buildWiringView() {
   return {
     controllers: [...wiringRegistry.controllers.keys()].sort(),
@@ -68,6 +81,116 @@ function registerProtocolTools(server) {
       return { content: [{ type: "text", text: JSON.stringify(buildWiringView(), null, 2) }] };
     }
   );
+  server.tool(
+    "get_catalog_ladder",
+    GET_CATALOG_LADDER_DESCRIPTION,
+    {
+      tier: z.enum(["L0", "L1"]).optional().describe("List one served rung's entry names instead of the ladder summary"),
+      name: z.string().optional().describe("With `tier` (required alongside it), return this single entry's full record")
+    },
+    async ({ tier, name }) => {
+      if (name && !tier) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `\`name\` needs a \`tier\`: entry names are unique only within a rung. Retry with { tier: "L1", name: "${name}" } (or "L0"), or omit \`name\` for the ladder summary.`
+            }
+          ],
+          isError: true
+        };
+      }
+      let index;
+      try {
+        index = await loadTierIndex();
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        return {
+          content: [{ type: "text", text: `Catalog tier index unavailable: ${e.message}` }],
+          isError: true
+        };
+      }
+      if (!tier) {
+        const ladder = Object.fromEntries(
+          Object.entries(index.tiers).map(([id, t]) => [
+            id,
+            {
+              unit: t.unit,
+              composesTier: t.composesTier,
+              status: t.status,
+              count: t.count,
+              servedHere: SERVED_TIERS.includes(id)
+            }
+          ])
+        );
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                {
+                  catalogId: index.catalogId,
+                  servedTiers: [...SERVED_TIERS],
+                  servingMap: "protocol server: L0+L1 (this tool) \xB7 gen-ui server: all tiers, for retrieval (get_catalog_tiers) \xB7 factory server: L2-L4, developer-facing",
+                  ladder
+                },
+                null,
+                2
+              )
+            }
+          ]
+        };
+      }
+      const rung = index.tiers[tier];
+      if (!rung) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Tier "${tier}" is absent from the catalog tier index (${Object.keys(index.tiers).join(", ")} present) \u2014 the index may predate it.`
+            }
+          ],
+          isError: true
+        };
+      }
+      if (name) {
+        const entry = rung.entries[name];
+        if (!entry) {
+          return {
+            content: [
+              {
+                type: "text",
+                text: `No ${tier} entry named "${name}". ${rung.count} entries in this tier \u2014 call this tool with just \`tier\` for the names.`
+              }
+            ],
+            isError: true
+          };
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify({ tier, name, entry }, null, 2) }]
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                tier,
+                unit: rung.unit,
+                composesTier: rung.composesTier,
+                status: rung.status,
+                count: rung.count,
+                entries: Object.keys(rung.entries).sort()
+              },
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
   server.tool(
     "protocol_status",
     PROTOCOL_STATUS_DESCRIPTION,