@wallarm-org/mcp 3.2.0 → 3.3.0-rc-fix-claude-code.1

package/dist/index.js

@@ -3,6 +3,7 @@ import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mc
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import fs from "fs";
 import path_0 from "path";
+import { fileURLToPath } from "url";
 function getEnumValues(entries) {
     const numericValues = Object.values(entries).filter((v)=>"number" == typeof v);
     const values = Object.entries(entries).filter(([k, _])=>-1 === numericValues.indexOf(+k)).map(([_, v])=>v);
@@ -40,6 +41,13 @@ function cleanRegex(source) {
     const end = source.endsWith("$") ? source.length - 1 : source.length;
     return source.slice(start, end);
 }
+function floatSafeRemainder(val, step) {
+    const ratio = val / step;
+    const roundedRatio = Math.round(ratio);
+    const tolerance = 4 * Number.EPSILON * Math.max(Math.abs(ratio), 1);
+    if (Math.abs(ratio - roundedRatio) < tolerance) return 0;
+    return ratio - roundedRatio;
+}
 function util_assignProp(target, prop, value) {
     Object.defineProperty(target, prop, {
         value,
@@ -961,6 +969,7 @@ function datetime(args) {
     return new RegExp(`^${dateSource}T(?:${timeRegex})$`);
 }
 const anyString = /^[\s\S]{0,}$/;
+const number = /^-?\d+(?:\.\d+)?$/;
 const regexes_boolean = /^(?:true|false)$/i;
 const lowercase = /^[^A-Z]*$/;
 const uppercase = /^[^a-z]*$/;
@@ -974,6 +983,120 @@ const _whenHasLength = (payload)=>{
     const val = payload.value;
     return !nullish(val) && void 0 !== val.length;
 };
+const numericOriginMap = {
+    number: "number",
+    bigint: "bigint",
+    object: "date"
+};
+const $ZodCheckLessThan = /*@__PURE__*/ $constructor("$ZodCheckLessThan", (inst, def)=>{
+    $ZodCheck.init(inst, def);
+    const origin = numericOriginMap[typeof def.value];
+    inst._zod.check = (payload)=>{
+        if (def.inclusive ? payload.value <= def.value : payload.value < def.value) return;
+        payload.issues.push({
+            origin: numericOriginMap[typeof payload.value] ?? origin,
+            code: "too_big",
+            maximum: "object" == typeof def.value ? def.value.getTime() : def.value,
+            input: payload.value,
+            inclusive: def.inclusive,
+            inst,
+            continue: !def.abort
+        });
+    };
+});
+const $ZodCheckGreaterThan = /*@__PURE__*/ $constructor("$ZodCheckGreaterThan", (inst, def)=>{
+    $ZodCheck.init(inst, def);
+    const origin = numericOriginMap[typeof def.value];
+    inst._zod.check = (payload)=>{
+        if (def.inclusive ? payload.value >= def.value : payload.value > def.value) return;
+        payload.issues.push({
+            origin: numericOriginMap[typeof payload.value] ?? origin,
+            code: "too_small",
+            minimum: "object" == typeof def.value ? def.value.getTime() : def.value,
+            input: payload.value,
+            inclusive: def.inclusive,
+            inst,
+            continue: !def.abort
+        });
+    };
+});
+const $ZodCheckMultipleOf = /*@__PURE__*/ $constructor("$ZodCheckMultipleOf", (inst, def)=>{
+    $ZodCheck.init(inst, def);
+    inst._zod.check = (payload)=>{
+        if (typeof payload.value !== typeof def.value) throw new Error("Cannot mix number and bigint in multiple_of check.");
+        const isMultiple = "bigint" == typeof payload.value ? def.value !== BigInt(0) && payload.value % def.value === BigInt(0) : 0 === floatSafeRemainder(payload.value, def.value);
+        if (isMultiple) return;
+        payload.issues.push({
+            origin: typeof payload.value,
+            code: "not_multiple_of",
+            divisor: def.value,
+            input: payload.value,
+            inst,
+            continue: !def.abort
+        });
+    };
+});
+const $ZodCheckNumberFormat = /*@__PURE__*/ $constructor("$ZodCheckNumberFormat", (inst, def)=>{
+    $ZodCheck.init(inst, def);
+    def.format = def.format || "float64";
+    const isInt = def.format?.includes("int");
+    const origin = isInt ? "int" : "number";
+    const [minimum, maximum] = NUMBER_FORMAT_RANGES[def.format];
+    inst._zod.check = (payload)=>{
+        const input = payload.value;
+        if (isInt) {
+            if (!Number.isInteger(input)) return void payload.issues.push({
+                expected: origin,
+                format: def.format,
+                code: "invalid_type",
+                continue: false,
+                input,
+                inst
+            });
+            if (!Number.isSafeInteger(input)) {
+                if (input > 0) payload.issues.push({
+                    input,
+                    code: "too_big",
+                    maximum: Number.MAX_SAFE_INTEGER,
+                    note: "Integers must be within the safe integer range.",
+                    inst,
+                    origin,
+                    inclusive: true,
+                    continue: !def.abort
+                });
+                else payload.issues.push({
+                    input,
+                    code: "too_small",
+                    minimum: Number.MIN_SAFE_INTEGER,
+                    note: "Integers must be within the safe integer range.",
+                    inst,
+                    origin,
+                    inclusive: true,
+                    continue: !def.abort
+                });
+                return;
+            }
+        }
+        if (input < minimum) payload.issues.push({
+            origin: "number",
+            input,
+            code: "too_small",
+            minimum,
+            inclusive: true,
+            inst,
+            continue: !def.abort
+        });
+        if (input > maximum) payload.issues.push({
+            origin: "number",
+            input,
+            code: "too_big",
+            maximum,
+            inclusive: true,
+            inst,
+            continue: !def.abort
+        });
+    };
+});
 const $ZodCheckMaxLength = /*@__PURE__*/ $constructor("$ZodCheckMaxLength", (inst, def)=>{
     var _a;
     $ZodCheck.init(inst, def);
@@ -1630,6 +1753,32 @@ const $ZodJWT = /*@__PURE__*/ $constructor("$ZodJWT", (inst, def)=>{
         });
     };
 });
+const $ZodNumber = /*@__PURE__*/ $constructor("$ZodNumber", (inst, def)=>{
+    $ZodType.init(inst, def);
+    inst._zod.pattern = number;
+    inst._zod.parse = (payload, _ctx)=>{
+        if (def.coerce) try {
+            payload.value = Number(payload.value);
+        } catch (_) {}
+        const input = payload.value;
+        if ("number" == typeof input && !Number.isNaN(input) && Number.isFinite(input)) return payload;
+        const received = "number" == typeof input ? Number.isNaN(input) ? "NaN" : Number.isFinite(input) ? void 0 : String(input) : void 0;
+        payload.issues.push({
+            expected: "number",
+            code: "invalid_type",
+            input,
+            inst,
+            ...received ? {
+                received
+            } : {}
+        });
+        return payload;
+    };
+});
+const $ZodNumberFormat = /*@__PURE__*/ $constructor("$ZodNumberFormat", (inst, def)=>{
+    $ZodCheckNumberFormat.init(inst, def);
+    $ZodNumber.init(inst, def);
+});
 const $ZodBoolean = /*@__PURE__*/ $constructor("$ZodBoolean", (inst, def)=>{
     $ZodType.init(inst, def);
     inst._zod.pattern = regexes_boolean;
@@ -2731,6 +2880,22 @@ function _isoDuration(Class, params) {
         ...normalizeParams(params)
     });
 }
+function _number(Class, params) {
+    return new Class(snapshotChecks({
+        type: "number",
+        checks: [],
+        ...normalizeParams(params)
+    }));
+}
+function _int(Class, params) {
+    return new Class({
+        type: "number",
+        check: "number_format",
+        abort: false,
+        format: "safeint",
+        ...normalizeParams(params)
+    });
+}
 function _boolean(Class, params) {
     return new Class({
         type: "boolean",
@@ -2748,6 +2913,45 @@ function _never(Class, params) {
         ...normalizeParams(params)
     });
 }
+function _lt(value, params) {
+    return new $ZodCheckLessThan({
+        check: "less_than",
+        ...normalizeParams(params),
+        value,
+        inclusive: false
+    });
+}
+function _lte(value, params) {
+    return new $ZodCheckLessThan({
+        check: "less_than",
+        ...normalizeParams(params),
+        value,
+        inclusive: true
+    });
+}
+function _gt(value, params) {
+    return new $ZodCheckGreaterThan({
+        check: "greater_than",
+        ...normalizeParams(params),
+        value,
+        inclusive: false
+    });
+}
+function _gte(value, params) {
+    return new $ZodCheckGreaterThan({
+        check: "greater_than",
+        ...normalizeParams(params),
+        value,
+        inclusive: true
+    });
+}
+function _multipleOf(value, params) {
+    return new $ZodCheckMultipleOf({
+        check: "multiple_of",
+        ...normalizeParams(params),
+        value
+    });
+}
 function _maxLength(maximum, params) {
     const ch = new $ZodCheckMaxLength({
         check: "max_length",
@@ -3459,6 +3663,37 @@ const stringProcessor = (schema, ctx, _json, _params)=>{
         ];
     }
 };
+const numberProcessor = (schema, ctx, _json, params)=>{
+    const json = _json;
+    const { minimum, maximum, multipleOf, exclusiveMaximum, exclusiveMinimum, isInt } = aggregateChecks(schema);
+    json.type = isInt ? "integer" : "number";
+    const exMin = "number" == typeof exclusiveMinimum && exclusiveMinimum >= (minimum ?? -1 / 0);
+    const exMax = "number" == typeof exclusiveMaximum && exclusiveMaximum <= (maximum ?? 1 / 0);
+    const legacy = "draft-04" === ctx.target || "openapi-3.0" === ctx.target;
+    if (exMin) if (legacy) {
+        json.minimum = exclusiveMinimum;
+        json.exclusiveMinimum = true;
+    } else json.exclusiveMinimum = exclusiveMinimum;
+    else if ("number" == typeof minimum) json.minimum = minimum;
+    if (exMax) if (legacy) {
+        json.maximum = exclusiveMaximum;
+        json.exclusiveMaximum = true;
+    } else json.exclusiveMaximum = exclusiveMaximum;
+    else if ("number" == typeof maximum) json.maximum = maximum;
+    if (multipleOf) {
+        const divisors = new Set();
+        for (const divisor of multipleOf)if (Number.isFinite(divisor) && 0 !== divisor) divisors.add(Math.abs(divisor));
+        else to_json_schema_handleUnrepresentable(schema, ctx, json, params, `A multipleOf divisor of ${divisor} cannot be represented in JSON Schema`);
+        const [first, ...rest] = divisors;
+        if (void 0 !== first) json.multipleOf = first;
+        if (rest.length) json.allOf = [
+            ...json.allOf ?? [],
+            ...rest.map((m)=>({
+                    multipleOf: m
+                }))
+        ];
+    }
+};
 const booleanProcessor = (_schema, _ctx, json, _params)=>{
     json.type = "boolean";
 };
@@ -4645,6 +4880,82 @@ const ZodJWT = /*@__PURE__*/ $constructor("ZodJWT", (inst, def)=>{
     $ZodJWT.init(inst, def);
     ZodStringFormat.init(inst, def);
 });
+const ZodNumber = /*@__PURE__*/ $constructor("ZodNumber", (inst, def)=>{
+    $ZodNumber.init(inst, def);
+    ZodType.init(inst, def);
+    inst._zod.processJSONSchema = (ctx, json, params)=>numberProcessor(inst, ctx, json, params);
+    inst.isFinite = true;
+}, /*@__PURE__*/ derived({
+    minValue: (inst)=>{
+        const { minimum, exclusiveMinimum } = aggregateChecks(inst);
+        return Math.max(minimum ?? -1 / 0, exclusiveMinimum ?? -1 / 0);
+    },
+    maxValue: (inst)=>{
+        const { maximum, exclusiveMaximum } = aggregateChecks(inst);
+        return Math.min(maximum ?? 1 / 0, exclusiveMaximum ?? 1 / 0);
+    },
+    isInt: (inst)=>{
+        const { isInt, multipleOf } = aggregateChecks(inst);
+        return !!isInt || !!multipleOf?.some(Number.isSafeInteger);
+    },
+    format: (inst)=>aggregateChecks(inst).format ?? null
+}, {
+    gt (value, params) {
+        return this.check(_gt(value, params));
+    },
+    gte (value, params) {
+        return this.check(_gte(value, params));
+    },
+    min (value, params) {
+        return this.check(_gte(value, params));
+    },
+    lt (value, params) {
+        return this.check(_lt(value, params));
+    },
+    lte (value, params) {
+        return this.check(_lte(value, params));
+    },
+    max (value, params) {
+        return this.check(_lte(value, params));
+    },
+    int (params) {
+        return this.check(schemas_int(params));
+    },
+    safe (params) {
+        return this.check(schemas_int(params));
+    },
+    positive (params) {
+        return this.check(_gt(0, params));
+    },
+    nonnegative (params) {
+        return this.check(_gte(0, params));
+    },
+    negative (params) {
+        return this.check(_lt(0, params));
+    },
+    nonpositive (params) {
+        return this.check(_lte(0, params));
+    },
+    multipleOf (value, params) {
+        return this.check(_multipleOf(value, params));
+    },
+    step (value, params) {
+        return this.check(_multipleOf(value, params));
+    },
+    finite () {
+        return this;
+    }
+}));
+function schemas_number(params) {
+    return _number(ZodNumber, params);
+}
+const ZodNumberFormat = /*@__PURE__*/ $constructor("ZodNumberFormat", (inst, def)=>{
+    $ZodNumberFormat.init(inst, def);
+    ZodNumber.init(inst, def);
+});
+function schemas_int(params) {
+    return _int(ZodNumberFormat, params);
+}
 const ZodBoolean = /*@__PURE__*/ $constructor("ZodBoolean", (inst, def)=>{
     $ZodBoolean.init(inst, def);
     ZodType.init(inst, def);
@@ -4997,6 +5308,7 @@ function refine(fn, _params = {}) {
 function superRefine(fn, params) {
     return _superRefine(fn, params);
 }
+const rulesraw_namespaceObject = "Every numeric utility is in px, not 4px steps: p-16 is 16px, p-4 is 4px. Translate Tailwind habits (p-4 → p-16, gap-6 → gap-24, w-64 → w-256).\n\nBefore composing a screen, call get_guideline for the pattern (app shell, list page, table, drawer, form, dialog, filters, empty state, settings, auth). Wrong → right:\n\n- p-5, gap-3, p-10 → stay on the scale: 1, 2, 4, 6, 8, 12, 16, 20, 24, 28, 32, 40, 48, 64…\n- space-y-4, margins per child → <VStack gap={16}>, <HStack gap={8}>\n- Padded page wrapper → Page > PageHeader / PageToolbar / PageContent own the 24px gutter\n- p-* on Card, DrawerBody, DialogBody, PageToolbar, Table → none; they own their padding\n- className on Text, Heading, Field, Drawer/Dialog Header/Body/Footer → wrap in your own element\n- Raw <h1>, <p>, <label> → <Heading as=\"h2\" size=\"lg\">, <Text size=\"sm\">, Field\n- <Text> default (16px) for body → size=\"sm\" (md is only an alias of sm)\n- leading-none (0px), leading-5 (5px) → leading-sm or leading-20\n- weight=\"semibold\" → weight is light|regular|medium|bold (medium = 450)\n- bg-primary, text-muted, bg-card, bg-white, text-gray-500 → bg-bg-primary, text-text-secondary, bg-bg-surface-1\n- text-error, bg-red-500 → danger tokens; categorical color → Badge color\n- dark: variant, setting data-theme → semantic tokens, useTheme().setTheme()\n- rounded-lg, rounded, rounded-[15px] → rounded-8 (controls), rounded-12 (panels)\n- shadow-* on DS components, z-* on overlays → never; they own both\n- focus:ring → focus-visible:ring-3 ring-focus-primary outline-none\n- size, DIALOG_SIZES, DRAWER_SIZES → width: Dialog 400 confirm, 560 default, 960 picker; Drawer 640 default, 700 Timeline form\n- Dialog, useToast from the root → @wallarm-org/design-system/Dialog, /Toast\n- Field invalid → error on the control + FieldError\n- Hand-built side menu → RemoteShell config={NavConfig}\n- ConfirmDialog, FilterBar, Combobox → compose Dialog parts, PageToolbar + FilterDropdown, Select + useSelectSearch\n- data-slot in tests → data-testid\n";
 const propMetadataSchema = schemas_object({
     name: schemas_string(),
     type: schemas_string(),
@@ -5022,6 +5334,10 @@ const exampleMetadataSchema = schemas_object({
     storyTitle: schemas_string().optional(),
     tags: schemas_array(schemas_string()).optional()
 });
+const componentDocSchema = schemas_object({
+    name: schemas_string(),
+    markdown: schemas_string()
+});
 const componentMetadataSchema = schemas_object({
     name: schemas_string(),
     description: schemas_string().optional(),
@@ -5029,7 +5345,8 @@ const componentMetadataSchema = schemas_object({
     props: schemas_array(propMetadataSchema),
     variants: schemas_array(variantMetadataSchema),
     subComponents: schemas_array(subComponentMetadataSchema),
-    examples: schemas_array(exampleMetadataSchema)
+    examples: schemas_array(exampleMetadataSchema),
+    docs: schemas_array(componentDocSchema).optional()
 });
 const tokenMetadataSchema = schemas_object({
     name: schemas_string(),
@@ -5046,6 +5363,39 @@ const designSystemMetadataSchema = schemas_object({
     components: schemas_array(componentMetadataSchema),
     tokens: schemas_array(tokenCategorySchema)
 });
+const guidelineSectionSchema = schemas_object({
+    id: schemas_string(),
+    heading: schemas_string(),
+    markdown: schemas_string()
+});
+const guidelineStorySchema = schemas_object({
+    name: schemas_string(),
+    code: schemas_string(),
+    description: schemas_string().optional()
+});
+const guidelineKindSchema = schemas_enum([
+    'foundation',
+    'pattern'
+]);
+const guidelineSchema = schemas_object({
+    slug: schemas_string(),
+    kind: guidelineKindSchema,
+    title: schemas_string(),
+    description: schemas_string(),
+    components: schemas_array(schemas_string()),
+    keywords: schemas_array(schemas_string()),
+    order: schemas_number(),
+    markdown: schemas_string(),
+    sections: schemas_array(guidelineSectionSchema),
+    stories: schemas_array(guidelineStorySchema).optional()
+});
+const guidelinesMetadataSchema = schemas_object({
+    version: schemas_string(),
+    rules: schemas_string(),
+    guidelines: schemas_array(guidelineSchema)
+});
+const DS_METADATA = path_0.join('@wallarm-org', 'design-system', 'dist', 'metadata', 'components.json');
+const describeSource = (source, version)=>'installed' === source.kind ? `Source: installed @wallarm-org/design-system v${version}` : `Source: bundled snapshot v${version} — may differ from your installed version (install @wallarm-org/design-system or pass --metadata-path)`;
 function parseMetadataPathArg(args) {
     const idx = args.indexOf('--metadata-path');
     if (-1 !== idx && idx + 1 < args.length) return args[idx + 1];
@@ -5054,11 +5404,27 @@ function findMetadataInNodeModules(startDir) {
     let dir = startDir;
     const root = path_0.parse(dir).root;
     while(dir !== root){
-        const candidate = path_0.join(dir, 'node_modules', '@wallarm-org', 'design-system', 'dist', 'metadata', 'components.json');
+        const candidate = path_0.join(dir, 'node_modules', DS_METADATA);
         if (fs.existsSync(candidate)) return candidate;
         dir = path_0.dirname(dir);
     }
 }
+function findMetadataInWorkspaces(cwd) {
+    for (const group of [
+        'apps',
+        'packages'
+    ]){
+        const groupDir = path_0.join(cwd, group);
+        if (fs.existsSync(groupDir)) for (const entry of fs.readdirSync(groupDir, {
+            withFileTypes: true
+        })){
+            if (!entry.isDirectory()) continue;
+            const candidate = path_0.join(groupDir, entry.name, 'node_modules', DS_METADATA);
+            if (fs.existsSync(candidate)) return candidate;
+        }
+    }
+}
+const defaultBundledPath = ()=>path_0.join(path_0.dirname(fileURLToPath(import.meta.url)), 'metadata', 'components.json');
 async function resolveViaImportMeta() {
     try {
         const resolved = import.meta.resolve('@wallarm-org/design-system/metadata');
@@ -5066,19 +5432,46 @@ async function resolveViaImportMeta() {
         if (fs.existsSync(filePath)) return filePath;
     } catch  {}
 }
-async function loadMetadata(args = process.argv) {
+async function loadMetadata(args = process.argv, { cwd = process.cwd(), bundledPath = defaultBundledPath(), resolveInstalled = resolveViaImportMeta } = {}) {
     let metadataPath;
+    let kind = 'installed';
     metadataPath = parseMetadataPathArg(args);
     if (metadataPath) metadataPath = path_0.resolve(metadataPath);
-    if (!metadataPath) metadataPath = await resolveViaImportMeta();
-    if (!metadataPath) metadataPath = findMetadataInNodeModules(process.cwd());
+    if (!metadataPath) metadataPath = await resolveInstalled();
+    if (!metadataPath) metadataPath = findMetadataInNodeModules(cwd) ?? findMetadataInWorkspaces(cwd);
+    if (!metadataPath && fs.existsSync(bundledPath)) {
+        metadataPath = bundledPath;
+        kind = 'bundled';
+    }
     if (!metadataPath) throw new Error("Could not find Wallarm Design System metadata.\n\nMake sure @wallarm-org/design-system is installed and built, or provide the path explicitly:\n  wallarm-ds-mcp --metadata-path ./path/to/components.json\n");
     if (!fs.existsSync(metadataPath)) throw new Error(`Metadata file not found at: ${metadataPath}`);
     const raw = JSON.parse(fs.readFileSync(metadataPath, 'utf-8'));
     const result = designSystemMetadataSchema.safeParse(raw);
     if (!result.success) throw new Error(`Invalid metadata format in ${metadataPath}:\n${result.error.message}\n\nThis might mean the design system version is incompatible with this MCP server version.`);
-    return result.data;
+    return {
+        metadata: result.data,
+        metadataPath,
+        source: {
+            kind,
+            path: metadataPath
+        }
+    };
+}
+function loadGuidelines(metadataPath, warn = (message)=>console.error('[wallarm-ds-mcp]', message)) {
+    const guidelinesPath = path_0.join(path_0.dirname(metadataPath), 'guidelines.json');
+    if (!fs.existsSync(guidelinesPath)) return;
+    try {
+        const raw = JSON.parse(fs.readFileSync(guidelinesPath, 'utf-8'));
+        if (raw && Array.isArray(raw.guidelines)) raw.guidelines = raw.guidelines.filter((g)=>guidelineKindSchema.safeParse(g?.kind).success);
+        const result = guidelinesMetadataSchema.safeParse(raw);
+        if (!result.success) throw new Error(result.error.message);
+        return result.data;
+    } catch (err) {
+        warn(`Ignoring ${guidelinesPath} (guidelines unavailable): ${err instanceof Error ? err.message : String(err)}`);
+        return;
+    }
 }
+const loadBundledGuidelines = (bundledPath = defaultBundledPath())=>loadGuidelines(bundledPath);
 function getComponentListContent(metadata) {
     const lines = [
         `# Wallarm Design System Components (v${metadata.version})`,
@@ -5110,105 +5503,467 @@ function getTokensContent(metadata) {
     }
     return lines.join('\n');
 }
+const RESPONSE_LIMIT = 40000;
+const splitUnion = (type)=>{
+    const parts = [];
+    let depth = 0;
+    let quote = '';
+    let start = 0;
+    for(let i = 0; i < type.length; i++){
+        const ch = type[i];
+        if (quote) {
+            if (ch === quote) quote = '';
+        } else if ('"' === ch || "'" === ch || '`' === ch) quote = ch;
+        else if ('{(<['.includes(ch ?? '')) depth++;
+        else if ('})>]'.includes(ch ?? '') && !('>' === ch && '=' === type[i - 1])) depth--;
+        else if ('|' === ch && 0 === depth) {
+            parts.push(type.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    parts.push(type.slice(start).trim());
+    return parts.filter(Boolean);
+};
+const formatType = (type, maxMembers = 8, maxLength = 160)=>{
+    const members = splitUnion(type).filter((m)=>'undefined' !== m);
+    let out = members.length > maxMembers ? `${members.slice(0, maxMembers).join(' | ')} | …(+${members.length - maxMembers})` : members.join(' | ') || type;
+    if (out.length > maxLength) out = `${out.slice(0, maxLength)}…`;
+    return out;
+};
+const cell = (text)=>text.replace(/\s*\n\s*/g, ' ').replace(/\|/g, '\\|');
+const oneLine = (text, max = 140)=>{
+    const flat = text.replace(/\s*\n\s*/g, ' ').trim();
+    const end = flat.search(/[.!?](\s|$)/);
+    const sentence = -1 === end ? flat : flat.slice(0, end + 1);
+    return sentence.length > max ? `${sentence.slice(0, max)}…` : sentence;
+};
+const formatPropsTable = (props, options = {})=>{
+    if (0 === props.length) return '';
+    const { brief = false, maxMembers = brief ? 8 : 30 } = options;
+    const hasRequired = props.some((p)=>p.required);
+    const hasDefault = props.some((p)=>void 0 !== p.defaultValue);
+    const hasDescription = props.some((p)=>p.description);
+    const head = [
+        'Prop',
+        'Type'
+    ];
+    if (hasRequired) head.push('Required');
+    if (hasDefault) head.push('Default');
+    if (hasDescription) head.push("Description");
+    const rows = props.map((p)=>{
+        const row = [
+            `\`${p.name}\``,
+            `\`${cell(formatType(p.type, maxMembers, brief ? 160 : 400))}\``
+        ];
+        if (hasRequired) row.push(p.required ? 'yes' : '');
+        if (hasDefault) row.push(void 0 !== p.defaultValue ? `\`${cell(p.defaultValue)}\`` : '');
+        if (hasDescription) {
+            const desc = p.description ?? '';
+            row.push(cell(brief ? oneLine(desc) : desc));
+        }
+        return `| ${row.join(' | ')} |`;
+    });
+    return [
+        `| ${head.join(' | ')} |`,
+        `|${head.map(()=>'---').join('|')}|`,
+        ...rows
+    ].join('\n');
+};
+const paginate = (text, page, nextCall, limit = RESPONSE_LIMIT)=>{
+    const budget = limit - 1000;
+    if (text.length <= budget && page <= 1) return text;
+    const blocks = text.split(/\n(?=#{1,3} )/);
+    const pages = [];
+    let current = '';
+    const push = (piece)=>{
+        if (current && current.length + piece.length + 1 > budget) {
+            pages.push(current);
+            current = '';
+        }
+        current = current ? `${current}\n${piece}` : piece;
+    };
+    for (const block of blocks)if (block.length <= budget) push(block);
+    else for (const line of block.split('\n'))push(line.slice(0, budget));
+    if (current) pages.push(current);
+    const total = pages.length;
+    const index = Math.min(Math.max(page, 1), total) - 1;
+    const footer = index + 1 < total ? `\n\n---\nPage ${index + 1}/${total}. Call again with ${nextCall(index + 2)} for the next page.` : `\n\n---\nPage ${index + 1}/${total} (last).`;
+    return `${pages[index]}${footer}`;
+};
 function getComponent(metadata, name) {
     return metadata.components.find((c)=>c.name.toLowerCase() === name.toLowerCase());
 }
-function formatComponentDetails(component) {
-    const lines = [];
-    lines.push(`# ${component.name}`);
-    if (component.description) lines.push('', component.description);
-    lines.push('', `**Import:** \`import { ${component.name} } from '${component.importPath}'\``);
-    if (component.props.length > 0) {
-        lines.push('', '## Props', '');
-        lines.push("| Prop | Type | Required | Default | Description |");
-        lines.push('|------|------|----------|---------|-------------|');
-        for (const prop of component.props){
-            const req = prop.required ? 'Yes' : 'No';
-            const def = prop.defaultValue ?? '-';
-            const desc = prop.description ?? '-';
-            lines.push(`| \`${prop.name}\` | \`${prop.type}\` | ${req} | \`${def}\` | ${desc} |`);
-        }
+function findSubComponentOwner(metadata, name) {
+    const n = name.toLowerCase();
+    for (const component of metadata.components){
+        const sub = component.subComponents.find((s)=>s.name.toLowerCase() === n);
+        if (sub) return {
+            component,
+            sub
+        };
     }
-    if (component.variants.length > 0) {
-        lines.push('', '## Variants', '');
-        for (const variant of component.variants){
-            const defaultNote = variant.defaultValue ? ` (default: \`${variant.defaultValue}\`)` : '';
-            const options = variant.options.length > 0 ? variant.options.map((o)=>`\`${o}\``).join(', ') : '_dynamically generated_';
-            lines.push(`- **${variant.name}**: ${options}${defaultNote}`);
-        }
+}
+const storyName = (example)=>example.storyTitle?.split('/').at(-1) ?? 'Story';
+function exampleEntries(component) {
+    const counts = new Map();
+    for (const e of component.examples)counts.set(e.name, (counts.get(e.name) ?? 0) + 1);
+    return component.examples.map((example)=>({
+            key: (counts.get(example.name) ?? 0) > 1 ? `${storyName(example)}/${example.name}` : example.name,
+            example
+        }));
+}
+function sharedProps(subs) {
+    const counts = new Map();
+    for (const sub of subs)for (const p of sub.props)if (!p.required && !p.description) counts.set(p.name, (counts.get(p.name) ?? 0) + 1);
+    const min = Math.max(3, Math.ceil(subs.length / 2));
+    return new Set([
+        ...counts
+    ].filter(([, n])=>n >= min).map(([name])=>name));
+}
+const withoutShared = (props, shared)=>props.filter((p)=>p.required || p.description || !shared.has(p.name));
+const sharedNote = (shared)=>shared.size > 0 ? `_Not repeated per sub-component — most also accept: ${[
+        ...shared
+    ].map((n)=>`\`${n}\``).join(', ')}._` : '';
+const call = (args)=>`\`{ ${Object.entries(args).map(([k, v])=>`${k}: ${'number' == typeof v ? v : `'${v}'`}`).join(', ')} }\``;
+const formatVariantList = (c)=>c.variants.map((v)=>{
+        const def = v.defaultValue ? ` (default: \`${v.defaultValue}\`)` : '';
+        const options = v.options.length > 0 ? v.options.map((o)=>`\`${o}\``).join(', ') : '_dynamically generated_';
+        return `- **${v.name}**: ${options}${def}`;
+    }).join('\n');
+function formatOverview(c) {
+    const lines = [
+        `# ${c.name}`
+    ];
+    if (c.description) lines.push('', c.description);
+    const exported = 0 === c.props.length && c.subComponents.length > 0 ? `${c.subComponents.slice(0, 4).map((x)=>x.name).join(', ')}${c.subComponents.length > 4 ? ', …' : ''}` : c.name;
+    lines.push('', `**Import:** \`import { ${exported} } from '${c.importPath}'\``);
+    if (c.props.length > 0) lines.push('', '## Props', '', formatPropsTable(c.props, {
+        brief: true
+    }));
+    if (c.variants.length > 0) lines.push('', '## Variants', '', formatVariantList(c));
+    if (c.subComponents.length > 0) {
+        lines.push('', `## Sub-components (${c.subComponents.length})`, '');
+        if (c.subComponents.some((s)=>s.description)) for (const s of c.subComponents)lines.push(`- **${s.name}**${s.description ? ` — ${oneLine(s.description)}` : ''}`);
+        else lines.push(c.subComponents.map((s)=>s.name).join(', '));
+        lines.push('', `Props of one: \`get_component\` ${call({
+            name: c.name,
+            section: c.subComponents[0]?.name ?? ''
+        })}; all: section \`'subcomponents'\`.`);
     }
-    if (component.subComponents.length > 0) {
-        lines.push('', '## Sub-components', '');
-        for (const sub of component.subComponents){
-            lines.push(`### ${sub.name}`);
-            if (sub.props.length > 0) {
-                lines.push('');
-                lines.push("| Prop | Type | Required | Default | Description |");
-                lines.push('|------|------|----------|---------|-------------|');
-                for (const prop of sub.props){
-                    const req = prop.required ? 'Yes' : 'No';
-                    const def = prop.defaultValue ?? '-';
-                    const desc = prop.description ?? '-';
-                    lines.push(`| \`${prop.name}\` | \`${prop.type}\` | ${req} | \`${def}\` | ${desc} |`);
-                }
-            }
-            lines.push('');
-        }
+    const entries = exampleEntries(c);
+    if (entries.length > 0) {
+        lines.push('', `## Examples (${entries.length})`, '');
+        for (const { key, example } of entries)lines.push(`- \`${key}\`${example.description ? ` — ${oneLine(example.description, 120)}` : ''}`);
+        lines.push('', `Code: \`get_example\` ${call({
+            component: c.name,
+            example: entries[0]?.key ?? ''
+        })}; all code: section \`'examples'\`.`);
     }
-    if (component.examples && component.examples.length > 0) {
-        lines.push('', '## Usage Examples', '');
-        for (const example of component.examples){
-            lines.push(`### ${example.name}`);
-            if (example.description) lines.push('', example.description);
-            lines.push('', '```tsx', example.code, '```', '');
-        }
+    if (c.docs && c.docs.length > 0) {
+        lines.push('', '## Usage docs', '');
+        for (const d of c.docs)lines.push(`- \`docs/${d.name}\` (${Math.round(d.markdown.length / 1000)}k chars)`);
+        lines.push('', `Read: \`get_component\` ${call({
+            name: c.name,
+            section: `docs/${c.docs[0]?.name}`
+        })}.`);
     }
     return lines.join('\n');
 }
-function getTokenCategory(metadata, name) {
-    return metadata.tokens.find((c)=>c.name.toLowerCase() === name.toLowerCase());
+function formatSubComponent(c, sub) {
+    const shared = sharedProps(c.subComponents);
+    const lines = [
+        `# ${c.name} › ${sub.name}`
+    ];
+    if (sub.description) lines.push('', sub.description);
+    lines.push('', `**Import:** \`import { ${sub.name} } from '${c.importPath}'\``);
+    const props = withoutShared(sub.props, shared);
+    lines.push('', props.length > 0 ? formatPropsTable(props) : '_No own props._');
+    const note = sharedNote(shared);
+    if (note) lines.push('', note);
+    const usedIn = exampleEntries(c).filter(({ example })=>new RegExp(`<${sub.name}\\b`).test(example.code)).map(({ key })=>`\`${key}\``);
+    if (usedIn.length > 0) lines.push('', `Used in examples (\`get_example\`): ${usedIn.slice(0, 10).join(', ')}${usedIn.length > 10 ? ', …' : ''}`);
+    return lines.join('\n');
 }
-function formatTokenCategory(category) {
-    const lines = [];
-    lines.push(`# ${category.name}`);
-    if (category.description) lines.push('', category.description);
-    lines.push('', `Total: ${category.tokens.length} tokens`, '');
-    lines.push('| Token | Value |');
-    lines.push('|-------|-------|');
-    for (const token of category.tokens)lines.push(`| \`${token.name}\` | \`${token.value}\` |`);
+function formatSubComponents(c) {
+    const shared = sharedProps(c.subComponents);
+    const lines = [
+        `# ${c.name} — sub-components`
+    ];
+    const note = sharedNote(shared);
+    if (note) lines.push('', note);
+    for (const sub of c.subComponents){
+        const props = withoutShared(sub.props, shared);
+        lines.push('', `### ${sub.name}`);
+        if (sub.description) lines.push('', sub.description);
+        lines.push('', props.length > 0 ? formatPropsTable(props) : '_No own props._');
+    }
     return lines.join('\n');
 }
-function scoreComponent(component, query) {
-    const q = query.toLowerCase();
-    const name = component.name.toLowerCase();
-    if (name === q) return 100;
-    if (name.startsWith(q)) return 80;
-    if (name.includes(q)) return 60;
-    if (component.description?.toLowerCase().includes(q)) return 40;
-    const propsMatch = component.props.some((p)=>p.name.toLowerCase().includes(q) || p.type.toLowerCase().includes(q));
-    if (propsMatch) return 30;
-    const variantsMatch = component.variants.some((v)=>v.name.toLowerCase().includes(q) || v.options.some((o)=>o.toLowerCase().includes(q)));
-    if (variantsMatch) return 20;
-    const subMatch = component.subComponents.some((sc)=>sc.name.toLowerCase().includes(q));
-    if (subMatch) return 15;
-    return 0;
+const formatExample = (key, example)=>[
+        `### ${key}`,
+        ...example.description ? [
+            '',
+            example.description
+        ] : [],
+        '',
+        '```tsx',
+        example.code,
+        '```'
+    ].join('\n');
+function formatExamples(c) {
+    return [
+        `# ${c.name} — examples`,
+        ...exampleEntries(c).map(({ key, example })=>`\n${formatExample(key, example)}`)
+    ].join('\n');
+}
+function formatProps(c) {
+    return [
+        `# ${c.name} — props`,
+        '',
+        c.props.length > 0 ? formatPropsTable(c.props) : '_No props._',
+        ...c.variants.length > 0 ? [
+            '',
+            '## Variants',
+            '',
+            formatVariantList(c)
+        ] : []
+    ].join('\n');
+}
+function componentSections(c) {
+    return [
+        'props',
+        ...c.subComponents.length > 0 ? [
+            'subcomponents'
+        ] : [],
+        ...c.examples.length > 0 ? [
+            'examples'
+        ] : [],
+        ...(c.docs ?? []).map((d)=>`docs/${d.name}`),
+        ...c.subComponents.map((s)=>s.name)
+    ];
 }
-function searchComponents(metadata, query) {
-    return metadata.components.map((c)=>({
+function formatComponent(c, options = {}) {
+    const { section, page = 1, related = '', source } = options;
+    const s = section?.trim().toLowerCase();
+    let body;
+    if (s && 'overview' !== s) if ('props' === s || 'variants' === s) body = formatProps(c);
+    else if ('subcomponents' === s || 'sub-components' === s) body = formatSubComponents(c);
+    else if ('examples' === s) body = formatExamples(c);
+    else if (s.startsWith('docs/')) {
+        const doc = c.docs?.find((d)=>d.name.toLowerCase() === s.slice(5));
+        if (doc) body = doc.markdown;
+    } else {
+        const sub = c.subComponents.find((x)=>x.name.toLowerCase() === s);
+        if (sub) body = formatSubComponent(c, sub);
+    }
+    else body = formatOverview(c) + related;
+    if (void 0 === body) return `Section "${section}" not found in ${c.name}.\n\nAvailable sections: ${componentSections(c).join(', ')}`;
+    const text = paginate(body, page, (next)=>call({
             name: c.name,
-            description: c.description,
-            importPath: c.importPath,
-            score: scoreComponent(c, query)
-        })).filter((r)=>r.score > 0).sort((a, b)=>b.score - a.score);
+            ...section && {
+                section
+            },
+            page: next
+        }));
+    const footer = s ? '' : `\n\n---\nMore: \`get_component\` with section ${componentSections(c).slice(0, 4).map((x)=>`\`'${x}'\``).join(', ')}${c.subComponents.length > 0 ? ' or a sub-component name' : ''}.`;
+    return `${text}${footer}${source ? `\n\n_${source}_` : ''}`;
+}
+const ROUTING = "Tools: `search_component` / `get_component` for components — `get_component` returns an overview, pass `section` for full props, sub-components or examples, and `get_example` for one example's code; `search_token` / `get_token_category` for design tokens; `list_guidelines` / `get_guideline` for foundations (spacing, color, typography, …) and patterns (screens and flows). Read the matching pattern with `get_guideline` before composing a screen.";
+function buildInstructions(rules, source) {
+    return `${rules.trim()}\n\n${ROUTING}${source ? `\n\n${source}.` : ''}`;
 }
-function scoreToken(token, category, query) {
+function listGuidelines(guidelines, kind) {
+    return guidelines.guidelines.filter((g)=>!kind || g.kind === kind);
+}
+function formatGuidelineList(list) {
+    if (0 === list.length) return 'No guidelines found.';
+    return list.map((g)=>{
+        const components = g.components.length > 0 ? `\n  Components: ${g.components.join(', ')}` : '';
+        return `- **${g.slug}** — ${g.title}: ${g.description}${components}`;
+    }).join('\n');
+}
+const splitLink = (link)=>{
+    const [path = '', anchor] = link.trim().split('#');
+    return {
+        path,
+        anchor: anchor || void 0
+    };
+};
+const normalizeSlug = (slug)=>splitLink(slug).path.toLowerCase().replace(/^(\.{1,2}\/)+/, '').replace(/\.md$/, '').replace(/^\/+|\/+$/g, '');
+const baseName = (slug)=>slug.slice(slug.lastIndexOf('/') + 1);
+function findGuideline(guidelines, slug) {
+    const s = normalizeSlug(slug);
+    return guidelines.guidelines.find((g)=>g.slug === s) ?? guidelines.guidelines.find((g)=>baseName(g.slug) === s);
+}
+const levenshtein = (a, b)=>{
+    let prev = Array.from({
+        length: b.length + 1
+    }, (_, i)=>i);
+    for(let i = 1; i <= a.length; i++){
+        const row = [
+            i
+        ];
+        for(let j = 1; j <= b.length; j++){
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            row[j] = Math.min((prev[j] ?? 0) + 1, (row[j - 1] ?? 0) + 1, (prev[j - 1] ?? 0) + cost);
+        }
+        prev = row;
+    }
+    return prev[b.length] ?? 0;
+};
+function nearestSlugs(guidelines, slug, limit = 3) {
+    const s = baseName(normalizeSlug(slug));
+    return guidelines.guidelines.map((g)=>{
+        const keywordHit = g.keywords.some((k)=>k.toLowerCase().includes(s) || s.includes(k.toLowerCase()));
+        return {
+            slug: g.slug,
+            distance: levenshtein(s, baseName(g.slug)) - (keywordHit ? 100 : 0)
+        };
+    }).sort((a, b)=>a.distance - b.distance).slice(0, limit).map((r)=>r.slug);
+}
+const STORIES = 'stories';
+const storiesFooter = (g)=>g.stories?.length ? `\n\n---\nLive stories (Storybook \`Patterns/${g.title}\`): ${g.stories.map((s)=>s.name).join(', ')}. Full, runnable code: \`get_guideline({ slug: '${g.slug}', section: '${STORIES}' })\`.` : '';
+const storiesText = (g, page)=>{
+    const body = (g.stories ?? []).map((s)=>[
+            `## ${s.name}`,
+            s.description ?? '',
+            `\`\`\`tsx\n${s.code}\n\`\`\``
+        ].filter(Boolean).join('\n\n')).join('\n\n');
+    return paginate(`# ${g.title} — Stories\n\n${body}`, page, (next)=>`\`{ slug: '${g.slug}', section: '${STORIES}', page: ${next} }\``);
+};
+function getGuidelineText(guidelines, slug, section, page = 1) {
+    const guideline = findGuideline(guidelines, slug);
+    if (!guideline) {
+        const hint = nearestSlugs(guidelines, slug);
+        return `Guideline "${slug}" not found.${hint.length > 0 ? `\n\nDid you mean: ${hint.join(', ')}?` : ''}`;
+    }
+    section ??= splitLink(slug).anchor;
+    const pageCall = (next)=>`\`{ slug: '${guideline.slug}'${section ? `, section: '${section}'` : ''}, page: ${next} }\``;
+    if (!section) return `${paginate(guideline.markdown, page, pageCall)}${storiesFooter(guideline)}`;
+    const id = section.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+    if (id === STORIES && guideline.stories?.length) return storiesText(guideline, page);
+    const match = guideline.sections.find((s)=>s.id === id);
+    if (!match) {
+        const ids = [
+            ...guideline.sections.map((s)=>s.id),
+            ...guideline.stories?.length ? [
+                STORIES
+            ] : []
+        ];
+        return `Section "${section}" not found in ${guideline.slug}.\n\nAvailable sections: ${ids.join(', ')}`;
+    }
+    return paginate(`# ${guideline.title} — ${match.heading}\n\n${match.markdown}`, page, pageCall);
+}
+function relatedGuidelines(guidelines, componentName) {
+    const name = componentName.toLowerCase();
+    return guidelines.guidelines.filter((g)=>g.components.some((c)=>c.toLowerCase() === name));
+}
+function formatRelatedGuidelines(related) {
+    if (0 === related.length) return '';
+    return `\n\nRelated guidelines (read with \`get_guideline\`): ${related.map((g)=>`${g.slug} (${g.title})`).join(', ')}`;
+}
+const normalize = (s)=>s.toLowerCase().replace(/[^a-z0-9/]/g, '');
+function getExampleText(c, example, page = 1) {
+    const entries = exampleEntries(c);
+    if (0 === entries.length) return `${c.name} has no examples.`;
+    const q = normalize(example);
+    const byName = entries.filter((e)=>normalize(e.example.name) === q);
+    const candidates = [
+        entries.filter((e)=>normalize(e.key) === q),
+        byName,
+        entries.filter((e)=>normalize(e.key).includes(q))
+    ].find((list)=>list.length > 0) ?? [];
+    const keys = entries.map((e)=>`\`${e.key}\``).join(', ');
+    if (candidates.length > 1) return `"${example}" matches several ${c.name} examples: ${candidates.map((e)=>`\`${e.key}\``).join(', ')}. Pass one of them.`;
+    const fuzzy = candidates[0] || q.length < 4 ? void 0 : entries.map((e)=>{
+        const key = normalize(e.key);
+        return {
+            e,
+            d: Math.min(levenshtein(q, key), levenshtein(q, key.split('/').at(-1) ?? ''))
+        };
+    }).filter(({ d })=>d <= Math.max(2, Math.floor(q.length / 4))).sort((a, b)=>a.d - b.d)[0]?.e;
+    const match = candidates[0] ?? fuzzy;
+    if (!match) return `Example "${example}" not found in ${c.name}.\n\nAvailable examples: ${keys}`;
+    const closest = fuzzy ? `Closest match for "${example}": \`${fuzzy.key}\`.\n\n` : '';
+    return closest + paginate(formatExample(match.key, match.example), page, (next)=>call({
+            component: c.name,
+            example: match.key,
+            page: next
+        }));
+}
+const COLOR_FAMILY_UTILITIES = {
+    text: [
+        'text'
+    ],
+    bg: [
+        'bg'
+    ],
+    border: [
+        'border'
+    ],
+    icon: [
+        'text'
+    ],
+    states: [
+        'bg'
+    ],
+    focus: [
+        'ring'
+    ],
+    syntax: [
+        'text'
+    ]
+};
+function tokenUtilities(tokenName) {
+    const name = tokenName.replace(/^--/, '');
+    const [, namespace = '', key = ''] = name.match(/^(color|spacing|radius|shadow|blur|icon|text|leading|tracking|font-weight|font)-(.+)$/) ?? [];
+    switch(namespace){
+        case 'color':
+            {
+                const family = key.split('-')[0] ?? '';
+                return (COLOR_FAMILY_UTILITIES[family] ?? [
+                    'bg',
+                    'text',
+                    'border'
+                ]).map((u)=>`${u}-${key}`);
+            }
+        case 'spacing':
+            return [
+                'p',
+                'm',
+                'gap',
+                'w',
+                'h'
+            ].map((u)=>`${u}-${key}`);
+        case 'radius':
+            return [
+                `rounded-${key}`
+            ];
+        case 'text':
+            return key.endsWith('--line-height') ? [] : [
+                `text-${key}`
+            ];
+        case 'font-weight':
+        case 'font':
+            return [
+                `font-${key}`
+            ];
+        case '':
+            return [];
+        default:
+            return [
+                `${namespace}-${key}`
+            ];
+    }
+}
+function scoreToken(token, utilities, category, query) {
     const q = query.toLowerCase();
     const name = token.name.toLowerCase();
     const val = token.value.toLowerCase();
     const cat = category.toLowerCase();
-    if (name === q || name === `--${q}`) return 100;
+    if (name === q || name === `--${q}` || utilities.includes(q)) return 100;
     if (name.startsWith(q) || name.startsWith(`--${q}`)) return 80;
-    if (name.includes(q)) return 60;
+    if (name.includes(q) || utilities.some((u)=>u.includes(q))) return 60;
     if (val === q) return 50;
     if (val.includes(q)) return 40;
     if (cat === q) return 30;
@@ -5218,29 +5973,344 @@ function scoreToken(token, category, query) {
 function searchTokens(metadata, query) {
     const results = [];
     for (const category of metadata.tokens)for (const token of category.tokens){
-        const score = scoreToken(token, category.name, query);
+        const utilities = tokenUtilities(token.name);
+        const score = scoreToken(token, utilities, category.name, query);
         if (score > 0) results.push({
             name: token.name,
             value: token.value,
             category: category.name,
+            utilities,
             score
         });
     }
     return results.sort((a, b)=>b.score - a.score);
 }
+function getTokenCategory(metadata, name) {
+    return metadata.tokens.find((c)=>c.name.toLowerCase() === name.toLowerCase());
+}
+function formatTokenCategory(category) {
+    const lines = [];
+    lines.push(`# ${category.name}`);
+    if (category.description) lines.push('', category.description);
+    lines.push('', `Total: ${category.tokens.length} tokens`, '');
+    lines.push('| Token | Value | Utility |');
+    lines.push('|-------|-------|---------|');
+    for (const token of category.tokens){
+        const utility = tokenUtilities(token.name).map((u)=>`\`${u}\``).join(' ');
+        lines.push(`| \`${token.name}\` | \`${token.value}\` | ${utility} |`);
+    }
+    return lines.join('\n');
+}
+const ALIASES = {
+    modal: [
+        'Dialog'
+    ],
+    popup: [
+        'Dialog',
+        'Popover'
+    ],
+    confirm: [
+        'Dialog'
+    ],
+    confirmation: [
+        'Dialog'
+    ],
+    sidebar: [
+        'RemoteShell',
+        'NavRail',
+        'AppShell',
+        'Drawer'
+    ],
+    'side panel': [
+        'Drawer'
+    ],
+    sheet: [
+        'Drawer'
+    ],
+    flyout: [
+        'Drawer',
+        'Popover'
+    ],
+    navigation: [
+        'NavRail',
+        'RemoteShell',
+        'TopHeader',
+        'Breadcrumbs'
+    ],
+    nav: [
+        'NavRail',
+        'RemoteShell'
+    ],
+    header: [
+        'TopHeader',
+        'Heading'
+    ],
+    layout: [
+        'Page',
+        'AppShell',
+        'Stack',
+        'Flex'
+    ],
+    toast: [
+        'Toast'
+    ],
+    snackbar: [
+        'Toast'
+    ],
+    notification: [
+        'Toast',
+        'Alert',
+        'Banner',
+        'NotificationCenter'
+    ],
+    callout: [
+        'Alert',
+        'Banner'
+    ],
+    dropdown: [
+        'Select',
+        'DropdownMenu'
+    ],
+    combobox: [
+        'Select'
+    ],
+    autocomplete: [
+        'Select'
+    ],
+    'context menu': [
+        'DropdownMenu'
+    ],
+    menu: [
+        'DropdownMenu'
+    ],
+    'empty state': [
+        'EmptyState'
+    ],
+    'no data': [
+        'EmptyState'
+    ],
+    'date picker': [
+        'DateInput',
+        'DateRangeInput',
+        'Calendar'
+    ],
+    datepicker: [
+        'DateInput',
+        'DateRangeInput',
+        'Calendar'
+    ],
+    'date range': [
+        'DateRangeInput'
+    ],
+    'time picker': [
+        'TimeInput'
+    ],
+    grid: [
+        'Table'
+    ],
+    bulk: [
+        'Table'
+    ],
+    'action bar': [
+        'Table'
+    ],
+    'row selection': [
+        'Table'
+    ],
+    'data table': [
+        'Table'
+    ],
+    datagrid: [
+        'Table'
+    ],
+    chart: [
+        'SimpleCharts'
+    ],
+    graph: [
+        'SimpleCharts'
+    ],
+    spinner: [
+        'Loader'
+    ],
+    toggle: [
+        'Switch',
+        'ToggleButton'
+    ],
+    upload: [
+        'FileUpload'
+    ],
+    dropzone: [
+        'FileUpload'
+    ],
+    hint: [
+        'Tooltip'
+    ],
+    chip: [
+        'Tag',
+        'Badge'
+    ],
+    pill: [
+        'Tag',
+        'Badge'
+    ],
+    label: [
+        'Tag',
+        'Badge'
+    ],
+    form: [
+        'Field',
+        'Input'
+    ],
+    'form field': [
+        'Field'
+    ],
+    'text field': [
+        'Input'
+    ],
+    multiline: [
+        'Textarea'
+    ],
+    search: [
+        'SearchInput',
+        'SearchModal'
+    ],
+    'command palette': [
+        'SearchModal'
+    ],
+    'code block': [
+        'CodeSnippet',
+        'CodeEditor'
+    ],
+    copy: [
+        'Copyable'
+    ],
+    wizard: [
+        'Stepper'
+    ],
+    collapse: [
+        'Accordion'
+    ],
+    collapsible: [
+        'Accordion'
+    ],
+    disclosure: [
+        'Accordion'
+    ],
+    paginator: [
+        'Pagination'
+    ],
+    otp: [
+        'InputOTP'
+    ],
+    divider: [
+        'Separator'
+    ],
+    'keyboard shortcut': [
+        'Kbd'
+    ],
+    hotkey: [
+        'Kbd'
+    ],
+    filter: [
+        'FilterInput',
+        'FilterDropdown',
+        'FilterCascade'
+    ],
+    status: [
+        'Badge',
+        'Indicator'
+    ]
+};
+const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'the',
+    'for',
+    'with',
+    'of',
+    'to',
+    'in',
+    'and',
+    'or',
+    'component',
+    'ui'
+]);
+const singular = (w)=>w.length > 4 && w.endsWith('ies') ? `${w.slice(0, -3)}y` : w.length > 3 && w.endsWith('s') && !w.endsWith('ss') ? w.slice(0, -1) : w;
+const words = (text)=>text.replace(/([a-z0-9])([A-Z])/g, '$1 $2').replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9]+/).filter((w)=>w && !STOP_WORDS.has(w)).map(singular);
+const coverage = (query, field)=>{
+    if (0 === query.length || 0 === field.length) return 0;
+    const hits = query.filter((q)=>field.some((f)=>f === q || q.length >= 4 && f.startsWith(q)));
+    return hits.length / query.length;
+};
+function scoreComponent(component, query, aliasHits) {
+    const q = query.trim().toLowerCase();
+    const name = component.name.toLowerCase();
+    if (name === q || words(component.name).join(' ') === words(query).join(' ')) return 100;
+    if (aliasHits.has(component.name)) return 90;
+    if (q && name.startsWith(q)) return 80;
+    if (q.length >= 3 && name.includes(q)) return 60;
+    const qw = words(query);
+    const nameScore = 60 * coverage(qw, words(component.name));
+    const descScore = 40 * coverage(qw, words(component.description ?? ''));
+    const propScore = 30 * coverage(qw, component.props.flatMap((p)=>words(p.name)));
+    const variantScore = 20 * coverage(qw, component.variants.flatMap((v)=>[
+            ...words(v.name),
+            ...v.options.flatMap(words)
+        ]));
+    const subScore = 15 * coverage(qw, component.subComponents.flatMap((s)=>words(s.name)));
+    return Math.round(Math.max(nameScore, descScore, propScore, variantScore, subScore));
+}
+function aliasMatches(query) {
+    const q = ` ${words(query).join(' ')} `;
+    const hits = new Set();
+    for (const [phrase, targets] of Object.entries(ALIASES))if (q.includes(` ${words(phrase).join(' ')} `)) for (const t of targets)hits.add(t);
+    return hits;
+}
+function searchComponents(metadata, query) {
+    const aliasHits = aliasMatches(query);
+    return metadata.components.map((c)=>({
+            name: c.name,
+            description: c.description,
+            importPath: c.importPath,
+            score: scoreComponent(c, query, aliasHits)
+        })).filter((r)=>r.score > 0).sort((a, b)=>b.score - a.score);
+}
 async function main() {
     const log = (...args)=>console.error('[wallarm-ds-mcp]', ...args);
     log('Loading metadata...');
-    const metadata = await loadMetadata();
-    log(`Loaded v${metadata.version}: ${metadata.components.length} components, ${metadata.tokens.length} token categories`);
+    const { metadata, metadataPath, source } = await loadMetadata();
+    const sourceLine = describeSource(source, metadata.version);
+    let guidelines = loadGuidelines(metadataPath);
+    let guidelinesSource = '';
+    if (!guidelines && 'installed' === source.kind) {
+        guidelines = loadBundledGuidelines();
+        if (guidelines) guidelinesSource = `\n\n_Guidelines: bundled snapshot v${guidelines.version} — your installed @wallarm-org/design-system v${metadata.version} ships no guidelines.json._`;
+    }
+    log(sourceLine, `(${metadataPath})`);
+    log(`Loaded v${metadata.version}: ${metadata.components.length} components, ${metadata.tokens.length} token categories, ${guidelines ? `${guidelines.guidelines.length} guidelines` : 'no guidelines.json (bundled rules)'}`);
+    const noGuidelines = `Guidelines are not available: @wallarm-org/design-system v${metadata.version} ships no guidelines.json. Upgrade the design system to get foundations and patterns.`;
     const server = new McpServer({
         name: 'wallarm-design-system',
         version: metadata.version
+    }, {
+        instructions: `${buildInstructions(guidelines?.rules ?? rulesraw_namespaceObject, sourceLine)}${guidelinesSource}`
     });
+    const notFound = (name)=>{
+        const suggestion = searchComponents(metadata, name).slice(0, 3);
+        const hint = suggestion.length > 0 ? `\n\nDid you mean: ${suggestion.map((s)=>s.name).join(', ')}?` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Component "${name}" not found.${hint}`
+                }
+            ]
+        };
+    };
     server.registerTool('search_component', {
-        description: "Search for components by name, description, props, or variants. Returns matched components sorted by relevance.",
+        description: 'Use when you need a UI element and do not know which DS component provides it (e.g. "modal", "date picker", "empty state", "sidebar"). Word-based search over names, descriptions, prop names, variants and common aliases; returns up to 10 components by relevance.',
         inputSchema: {
-            query: schemas_string().describe('Search query — component name, prop name, variant, or keyword')
+            query: schemas_string().describe('What you need — a component name, a UI concept ("toast", "dropdown") or a prop name')
         }
     }, async ({ query })=>{
         const results = searchComponents(metadata, query);
@@ -5266,35 +6336,68 @@ async function main() {
         };
     });
     server.registerTool('get_component', {
-        description: 'Get full details for a specific component: props, variants, sub-components, and import path.',
+        description: "Use when you know the component and need its API before writing code. Without `section` returns an overview: import, props, variants, sub-component names, example names, usage docs and related guidelines. Pass `section` for full detail: 'props', 'subcomponents', 'examples', 'docs/<Name>' or a sub-component name (e.g. 'TableColumnMenu'). Long sections are paginated — pass `page`.",
         inputSchema: {
-            name: schemas_string().describe('Component name (case-insensitive), e.g. "Button", "Alert", "Select"')
+            name: schemas_string().describe('Component name (case-insensitive), e.g. "Button", "Alert", "Select"'),
+            section: schemas_string().optional().describe("Omit for the overview; or 'props', 'subcomponents', 'examples', 'docs/<Name>', or a sub-component name"),
+            page: schemas_number().int().min(1).optional().describe('Page of a paginated response, from 1')
         }
-    }, async ({ name })=>{
+    }, async ({ name, section, page })=>{
         const component = getComponent(metadata, name);
         if (!component) {
-            const suggestion = searchComponents(metadata, name).slice(0, 3);
-            const hint = suggestion.length > 0 ? `\n\nDid you mean: ${suggestion.map((s)=>s.name).join(', ')}?` : '';
+            const owner = findSubComponentOwner(metadata, name);
+            if (!owner) return notFound(name);
+            const text = formatComponent(owner.component, {
+                section: owner.sub.name,
+                page,
+                source: sourceLine
+            });
             return {
                 content: [
                     {
                         type: 'text',
-                        text: `Component "${name}" not found.${hint}`
+                        text
                     }
                 ]
             };
         }
+        const related = guidelines ? formatRelatedGuidelines(relatedGuidelines(guidelines, component.name)) : '';
+        const text = formatComponent(component, {
+            section,
+            page,
+            related,
+            source: sourceLine
+        });
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text
+                }
+            ]
+        };
+    });
+    server.registerTool('get_example', {
+        description: 'Use when you want working code for one usage of a component — copy the pattern instead of guessing composition. Example names come from the `get_component` overview; close names are matched, and a miss lists every example.',
+        inputSchema: {
+            component: schemas_string().describe('Component name, e.g. "Table", "SimpleCharts"'),
+            example: schemas_string().describe('Example name from get_component, e.g. "WithPagination" or "AreaChart/Default"'),
+            page: schemas_number().int().min(1).optional().describe('Page of a paginated response, from 1')
+        }
+    }, async ({ component: name, example, page })=>{
+        const component = getComponent(metadata, name) ?? findSubComponentOwner(metadata, name)?.component;
+        if (!component) return notFound(name);
         return {
             content: [
                 {
                     type: 'text',
-                    text: formatComponentDetails(component)
+                    text: getExampleText(component, example, page)
                 }
             ]
         };
     });
     server.registerTool('search_token', {
-        description: 'Search for design tokens by name, value, or category. Returns matched tokens sorted by relevance.',
+        description: 'Use when styling needs a colour, spacing, radius, shadow or type value — find the token and the Tailwind class to write (e.g. "text-primary", "surface", "spacing-8", "#ff6633", "bg-bg-surface-2"). Returns up to 20 tokens with value and utility classes.',
         inputSchema: {
             query: schemas_string().describe('Search query — token name (e.g. "spacing-8"), value (e.g. "#ff6633"), or category (e.g. "colors-primary")')
         }
@@ -5308,7 +6411,10 @@ async function main() {
                 }
             ]
         };
-        const text = results.slice(0, 20).map((r)=>`- \`${r.name}\`: \`${r.value}\`  _(${r.category})_`).join('\n');
+        const text = results.slice(0, 20).map((r)=>{
+            const utilities = r.utilities.length > 0 ? ` → ${r.utilities.map((u)=>`\`${u}\``).join(' ')}` : '';
+            return `- \`${r.name}\`: \`${r.value}\`${utilities}  _(${r.category})_`;
+        }).join('\n');
         return {
             content: [
                 {
@@ -5319,11 +6425,12 @@ async function main() {
         };
     });
     server.registerTool('get_token_category', {
-        description: 'Get all tokens in a specific category (e.g. "spacing", "colors-primary", "typography").',
+        description: 'Use when you need the whole scale of one token category (e.g. all spacing steps, all semantic colours) with values and Tailwind classes. Large categories are paginated — pass `page`.',
         inputSchema: {
-            name: schemas_string().describe('Category name (case-insensitive), e.g. "spacing", "colors-primary", "shadow"')
+            name: schemas_string().describe('Category name (case-insensitive), e.g. "spacing", "colors-primary", "shadow"'),
+            page: schemas_number().int().min(1).optional().describe('Page of a paginated response, from 1')
         }
-    }, async ({ name })=>{
+    }, async ({ name, page = 1 })=>{
         const category = getTokenCategory(metadata, name);
         if (!category) {
             const categories = metadata.tokens.map((c)=>c.name);
@@ -5336,15 +6443,47 @@ async function main() {
                 ]
             };
         }
+        const text = paginate(formatTokenCategory(category), page, (next)=>`\`{ name: '${category.name}', page: ${next} }\``);
         return {
             content: [
                 {
                     type: 'text',
-                    text: formatTokenCategory(category)
+                    text
                 }
             ]
         };
     });
+    server.registerTool('list_guidelines', {
+        description: "Use when starting a screen or flow, or unsure about spacing, colour or typography rules — lists foundations and patterns with slug, title, description and components.",
+        inputSchema: {
+            kind: schemas_enum([
+                'foundation',
+                'pattern'
+            ]).optional().describe('Only list foundations or only patterns; omit for both')
+        }
+    }, async ({ kind })=>({
+            content: [
+                {
+                    type: 'text',
+                    text: guidelines ? `${formatGuidelineList(listGuidelines(guidelines, kind))}${guidelinesSource}` : noGuidelines
+                }
+            ]
+        }));
+    server.registerTool('get_guideline', {
+        description: "Use when composing a screen (read the matching pattern first) or applying a foundation — returns the guideline as markdown. Pass `section` to get one section only; `section: 'stories'` returns a pattern's full live-story code (paginated — pass `page`).",
+        inputSchema: {
+            slug: schemas_string().describe('Guideline slug from list_guidelines, e.g. "patterns/entity-table" or "foundations/spacing"'),
+            section: schemas_string().optional().describe('Section id or heading, e.g. "rules", "examples", "states", "stories"'),
+            page: schemas_number().int().min(1).optional().describe('Page of a paginated response, from 1')
+        }
+    }, async ({ slug, section, page })=>({
+            content: [
+                {
+                    type: 'text',
+                    text: guidelines ? `${getGuidelineText(guidelines, slug, section, page)}${guidelinesSource}` : noGuidelines
+                }
+            ]
+        }));
     server.registerResource('component-list', 'ds://components', {
         description: 'List of all Wallarm Design System components with import paths',
         mimeType: 'text/markdown'
@@ -5390,7 +6529,9 @@ async function main() {
             contents: [
                 {
                     uri: uri.href,
-                    text: formatComponentDetails(component),
+                    text: formatComponent(component, {
+                        source: sourceLine
+                    }),
                     mimeType: 'text/markdown'
                 }
             ]