@nyuchi/mzizi-mcp 0.13.0 → 0.14.0

package/dist/tools.js

@@ -25,7 +25,20 @@ import { bundledRegistry } from "./registry.js";
 import { dispatchFundiA2A, FUNDI_SUBMIT_TOOL, FUNDI_STATUS_TOOL, FUNDI_CANCEL_TOOL, } from "./fundi-a2a.js";
 import { jsonContent, toolError } from "./tool-result.js";
 import { signInRequired } from "./access.js";
+import { CHARACTER_LIMIT, fitToLimit } from "./limits.js";
 import { BUNDLED_SKILLS, SKILL_CATEGORIES, SKILLS_VERSION } from "./generated/skills.js";
+/** The MCP resource URI of a skill's SKILL.md body, and of a file it ships. */
+export const skillUri = (name) => `mzizi://skills/${name}`;
+export const skillFileUri = (name, path) => `mzizi://skills/${name}/${path}`;
+/** A skill as the tool returns it: the body in full, its files as a list (content on request). */
+export function skillView(skill) {
+    const { files, ...rest } = skill;
+    return {
+        ...rest,
+        uri: skillUri(skill.name),
+        files: files.map((f) => ({ path: f.path, mimeType: f.mimeType, bytes: f.bytes, encoding: f.encoding, uri: skillFileUri(skill.name, f.path) })),
+    };
+}
 export const TOOL_PREFIX = "mzizi_";
 /** Unwrap a registry result into an MCP tool result, keeping the failure readable. */
 function respond(result, wrapKey) {
@@ -40,6 +53,7 @@ function respond(result, wrapKey) {
  */
 const READ = {
     readOnlyHint: true,
+    destructiveHint: false,
     idempotentHint: true,
     openWorldHint: false,
 };
@@ -60,6 +74,9 @@ const READ = {
  * are always reported, so nothing is hidden and nothing is silently truncated.
  */
 const LIST_DEFAULT_LIMIT = 400;
+/** Default and maximum hits per `search` call (the default was the registry's own 50). */
+const SEARCH_DEFAULT_LIMIT = 50;
+const SEARCH_MAX_LIMIT = 200;
 /**
  * A number argument that also accepts the string form of itself.
  *
@@ -180,13 +197,135 @@ function astroSection(doc) {
         files: doc.files.map((f) => f.encoding === "base64" ? { path: f.path, type: f.type, target: f.target, encoding: f.encoding } : f),
     };
 }
-/** The React build, second and labelled: the registry's `/v1/ui/{name}` body, unchanged. */
-function reactSection(body) {
+/** Lowercase hex SHA-256 of a UTF-8 string. Web Crypto, so it runs in the Worker and the stdio bin. */
+async function sha256Hex(text) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(text));
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * The source with its `//` line and `/* *\/` block comments removed, so an import
+ * written in a comment is not read as one. String and template literals are copied
+ * through untouched, so a `//` inside `"https://…"` does not start a comment.
+ */
+function stripComments(src) {
+    let out = "";
+    let i = 0;
+    while (i < src.length) {
+        const c = src[i];
+        const next = src[i + 1];
+        if (c === '"' || c === "'" || c === "`") {
+            let j = i + 1;
+            while (j < src.length && src[j] !== c)
+                j += src[j] === "\\" ? 2 : 1;
+            out += src.slice(i, j + 1);
+            i = j + 1;
+        }
+        else if (c === "/" && next === "/") {
+            const end = src.indexOf("\n", i);
+            i = end === -1 ? src.length : end;
+        }
+        else if (c === "/" && next === "*") {
+            const end = src.indexOf("*/", i + 2);
+            // Keep a space so the tokens either side of the comment stay apart.
+            out += " ";
+            i = end === -1 ? src.length : end + 2;
+        }
+        else {
+            out += c;
+            i += 1;
+        }
+    }
+    return out;
+}
+/**
+ * Every `@/…` module specifier a source file imports, re-exports or loads with a
+ * dynamic `import("@/…")`, in first-seen order. Comments are ignored.
+ */
+function aliasImports(content) {
+    const seen = new Set();
+    const code = stripComments(content);
+    for (const m of code.matchAll(/(?:\bfrom|\bimport)\s*\(?\s*["'`](@\/[^"'`]+)["'`]/g)) {
+        if (m[1])
+            seen.add(m[1]);
+    }
+    return [...seen];
+}
+/** The `@/…` specifier a file installed at `target` answers (`lib/icons/index.tsx` → `@/lib/icons`). */
+function aliasOfTarget(target) {
+    return "@/" + target.replace(/\.(tsx?|jsx?)$/, "").replace(/\/index$/, "");
+}
+const UI_PREFIX = "https://api.mzizi.dev/v1/ui/";
+/**
+ * The raw file at exactly `ref`: `https://raw.githubusercontent.com/<owner>/<repo>/<ref>/<path>`.
+ * Null when the registry is not a GitHub repository or the file has no path.
+ */
+function pinnedFileUrl(repository, ref, path) {
+    const m = /^https:\/\/github\.com\/([^/]+)\/([^/]+?)(?:\.git)?\/?$/.exec(repository);
+    if (!m || !path)
+        return null;
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    return `https://raw.githubusercontent.com/${m[1]}/${m[2]}/${ref}/${encoded}`;
+}
+/**
+ * What a consumer needs to vendor the React build without calling the API
+ * (mzizi-registry#532): the registry commit this answer comes from, each file's
+ * install target, SHA-256 and a URL pinned to that commit, each `@/` import with
+ * the declared registry dependency that installs it (or null when none does),
+ * and, labelled as live, the API item URL, which serves whatever commit the API
+ * is pinned to and can differ from `registry.ref`.
+ */
+async function vendorSection(body, r) {
+    const name = String(body.name ?? "");
+    const files = (Array.isArray(body.files) ? body.files : []);
+    const deps = (Array.isArray(body.registryDependencies) ? body.registryDependencies : []);
+    // The alias each declared dependency's files answer, so an import can be matched to its installer.
+    const provides = new Map();
+    for (const dep of deps) {
+        if (!dep.startsWith(UI_PREFIX))
+            continue;
+        const depName = dep.slice(UI_PREFIX.length);
+        const got = r.getComponent(depName);
+        if (!got.ok)
+            continue;
+        for (const f of (got.data.files ?? [])) {
+            if (f.target)
+                provides.set(aliasOfTarget(f.target), depName);
+        }
+    }
+    const own = new Set(files.flatMap((f) => (f.target ? [aliasOfTarget(f.target)] : [])));
+    const imports = [...new Set(files.flatMap((f) => aliasImports(f.content ?? "")))]
+        .filter((spec) => !own.has(spec))
+        .map((spec) => ({ alias: spec, providedBy: provides.get(spec) ?? null }));
+    return {
+        registry: { repository: r.pin.repository, ref: r.pin.ref },
+        files: await Promise.all(files.map(async (f) => ({
+            path: f.path ?? null,
+            target: f.target ?? null,
+            url: pinnedFileUrl(r.pin.repository, r.pin.ref, f.path),
+            sha256: typeof f.content === "string" ? await sha256Hex(f.content) : null,
+        }))),
+        imports,
+        live: {
+            url: `${UI_PREFIX}${encodeURIComponent(name)}`,
+            note: "Live, not pinned: the API serves the registry commit it is deployed at, which can differ from registry.ref, " +
+                "so its files may not match these sha256 values. Use files[].url for the pinned source.",
+        },
+        note: "Components have no version numbers of their own: pin a vendored copy to registry.ref and check each file's sha256. " +
+            "Each sha256 is of the registry source at path@registry.ref (what files[].url serves). A file written by `shadcn add` " +
+            "can differ from it: shadcn strips \"use client\" when the project sets rsc: false, and rewrites @/ aliases to the " +
+            "project's own, so hash the registry source, not the installed file. " +
+            "An import whose providedBy is null is not installed by any declared registry dependency. @/lib/utils is provided " +
+            "by the registry's utils item, or by shadcn init in a project that ran it.",
+    };
+}
+/** The React build, second and labelled: the registry's `/v1/ui/{name}` body, plus `vendor` install metadata. */
+async function reactSection(body, r) {
     const name = String(body.name ?? "");
     return {
         build: "react",
         status: "deprioritised",
         install: `npx shadcn@latest add https://api.mzizi.dev/v1/ui/${encodeURIComponent(name)}`,
+        vendor: await vendorSection(body, r),
         ...body,
     };
 }
@@ -202,24 +341,68 @@ export function registerMziziTools(server, opts) {
     // 1 ─ search
     server.registerTool(note("search"), {
         title: "Search Mzizi",
-        description: "Search the registry by words: components, conventions, AI instruction sets and releases. Start here when you do not know the exact name of what you want. A component hit with `rustCrate` has a Mzizi Roots (Rust) implementation, which is the lead; at an equal score it ranks first. Documentation pages are searched by the docs_* tools.",
-        inputSchema: {
-            query: z.string().min(1).describe("Free-text search term."),
-        },
+        description: "Search the registry by words: components, conventions, AI instruction sets and releases. Start here when you do not know the exact name of what you want; use mzizi_get_component once you have a component's name. A component hit with `rustCrate` has a Mzizi Roots (Rust) implementation, which is the lead; at an equal score it ranks first. Documentation pages are searched by the docs_* tools. " +
+            `Paged: up to ${SEARCH_DEFAULT_LIMIT} hits per call and at most ${CHARACTER_LIMIT} characters; meta.has_more and meta.next_offset say how to get the rest.`,
+        inputSchema: z.object({
+            query: z.string().min(1).max(500).describe("Free-text search term, e.g. 'button' or 'date picker'. Every word must match."),
+            limit: NUM.int().positive().optional().describe(`Hits per call (default ${SEARCH_DEFAULT_LIMIT}, at most ${SEARCH_MAX_LIMIT}).`),
+            offset: NUM.int().min(0).optional().describe("Hits to skip, for paging. Use meta.next_offset from the previous call."),
+        }),
+        outputSchema: z.object({
+            results: z.object({
+                data: z.array(z.looseObject({
+                    kind: z.string(),
+                    name: z.string(),
+                    title: z.string().optional(),
+                    description: z.string().optional(),
+                    rustCrate: z.string().optional(),
+                    astroFile: z.string().optional(),
+                })),
+                meta: z.looseObject({
+                    total: z.number(),
+                    count: z.number(),
+                    offset: z.number(),
+                    has_more: z.boolean(),
+                    next_offset: z.number().optional(),
+                }),
+            }),
+        }),
         annotations: READ,
-    }, async ({ query }) => respond((await reg()).search(query), "results"));
+    }, async ({ query, limit, offset }) => {
+        const res = (await reg()).search(query, Number.MAX_SAFE_INTEGER);
+        const all = res.data.data;
+        const skip = offset ?? 0;
+        const take = Math.min(limit ?? SEARCH_DEFAULT_LIMIT, SEARCH_MAX_LIMIT);
+        const render = (page) => {
+            const next = skip + page.length;
+            const hasMore = next < all.length;
+            return {
+                data: page,
+                meta: {
+                    ...res.data.meta,
+                    total: all.length,
+                    count: page.length,
+                    offset: skip,
+                    has_more: hasMore,
+                    ...(hasMore ? { next_offset: next } : {}),
+                },
+            };
+        };
+        const { result } = fitToLimit(all.slice(skip, skip + take), render);
+        return jsonContent(result, "results");
+    });
     // 2 ─ get_component — one read, everything, Rust first
     server.registerTool(note("get_component"), {
         title: "Get a component",
-        description: "Fetch one component in full, Rust first. When the component has a Mzizi Roots (Rust, Dioxus) implementation, `rust` comes first: its crate, the `cargo add` line, its CONTRACT clause block and the `.rs` source inline. `astro` follows when the component has a pure Astro implementation (mzizi-registry#397): its `mzizi add --target astro` line, the files it installs into src/components/mzizi/ and their dependencies; null otherwise. `react` follows: the React build (deprioritised; it keeps working, new work goes to Rust), shadcn-shaped with files[] inline and its `npx shadcn add` line. With no Rust, `rust` is null and `lead` is \"react\". " +
+        description: "Fetch one component in full, Rust first. When the component has a Mzizi Roots (Rust) implementation, `rust` comes first (Roots' crates are built on Dioxus 0.7 today and are moving to Mzizi's own renderer): its crate, the `cargo add` line, its CONTRACT clause block and the `.rs` source inline. `astro` follows when the component has a pure Astro implementation (mzizi-registry#397): its `mzizi add --target astro` line, the files it installs into src/components/mzizi/ and their dependencies; null otherwise. `react` follows: the React build (deprioritised; it keeps working, new work goes to Rust), shadcn-shaped with files[] inline, its `npx shadcn add` line, and `vendor`: the registry commit, each file's install target, sha256 and a raw URL pinned to that commit, each `@/` import with the dependency that installs it, and the live API item URL (labelled live: it can serve a different commit). Each sha256 is of the registry source at path@ref; a file `shadcn add` writes can differ (it strips \"use client\" under rsc: false and rewrites aliases). With no Rust, `rust` is null and `lead` is \"react\". " +
             "Add docs (use cases, variants, a11y: the documented contract) and version history (from the changelog) with `include`. Former nyuchi-* names resolve to their mzizi-* successors.",
-        inputSchema: {
-            name: z.string().min(1).describe("Component name, e.g. 'button'."),
+        inputSchema: z.object({
+            name: z.string().max(200).min(1).describe("Component name, e.g. 'button'."),
             include: z
                 .array(z.enum(["docs", "versions"]))
                 .optional()
                 .describe("Extra sections to fetch. Omit for the implementations only."),
-        },
+        }),
         annotations: READ,
     }, async ({ name, include }) => {
         const r = await reg();
@@ -237,10 +420,12 @@ export function registerMziziTools(server, opts) {
             note: rust.ok
                 ? `Rust first: "${current}" has a Mzizi Roots implementation in the ${rust.data.crate.name} crate — use it. ` +
                     "The React build below is deprioritised: it keeps working, but new work goes to Rust."
-                : `No Mzizi Roots (Rust) implementation yet. ${rust.message}`,
+                : rust.message,
             rust: rust.ok ? rustSection(rust.data, r.pin.ref) : null,
             astro: astro.ok ? astroSection(astro.data) : null,
-            react: react.ok ? reactSection(react.data) : { build: "react", error: react.message },
+            react: react.ok
+                ? await reactSection(react.data, r)
+                : { build: "react", error: react.message },
         };
         // A failure in an extra section must not discard the component the caller
         // actually asked for -- it is reported alongside it.
@@ -259,8 +444,8 @@ export function registerMziziTools(server, opts) {
             "Returns a lean row per component (name, type, node, owner, collection, and rustCrate " +
             "when it has a Mzizi Roots (Rust) implementation, which is the lead) — use " +
             "get_component for one component in full, or search when you only have words. " +
-            `Paged: up to ${LIST_DEFAULT_LIMIT} rows per call, with total and hasMore reported.`,
-        inputSchema: {
+            `Paged: up to ${LIST_DEFAULT_LIMIT} rows and at most ${CHARACTER_LIMIT} characters per call; total, has_more and next_offset say how to get the rest.`,
+        inputSchema: z.object({
             // No .max(): the node set is uncapped, and a Zod bound would reject a filter
             // before it reached the data, turning a new node into a schema error.
             node: NUM.int()
@@ -268,15 +453,15 @@ export function registerMziziTools(server, opts) {
                 .optional()
                 .describe("Filter by node number (uncapped)."),
             owner: z
-                .string()
+                .string().max(100)
                 .optional()
                 .describe("Filter by owner: mzizi | nyuchi | bundu | framework."),
             collection: z
-                .string()
+                .string().max(100)
                 .optional()
                 .describe("Filter by collection, e.g. primitives | brand | pages | resilience."),
             type: z
-                .string()
+                .string().max(100)
                 .optional()
                 .describe("Filter by registry type, e.g. registry:ui | registry:lib | registry:block."),
             rust: BOOL.optional().describe("true: only components with a Mzizi Roots (Rust) implementation; false: only those without."),
@@ -284,12 +469,30 @@ export function registerMziziTools(server, opts) {
             limit: NUM.int()
                 .positive()
                 .optional()
-                .describe(`Rows per call (default ${LIST_DEFAULT_LIMIT}).`),
+                .describe(`Rows per call (default ${LIST_DEFAULT_LIMIT}). A page also stops at ${CHARACTER_LIMIT} characters.`),
             offset: NUM.int()
                 .min(0)
                 .optional()
                 .describe("Rows to skip, for paging."),
-        },
+        }),
+        outputSchema: z.object({
+            count: z.number(),
+            total: z.number(),
+            offset: z.number(),
+            has_more: z.boolean(),
+            next_offset: z.number().optional(),
+            hasMore: z.boolean(),
+            nextOffset: z.number().optional(),
+            hint: z.string().optional(),
+            registryTotal: z.number().optional(),
+            withRust: z.number(),
+            withAstro: z.number(),
+            items: z.array(z.looseObject({
+                name: z.unknown(),
+                rustCrate: z.string().optional(),
+                astroFile: z.string().optional(),
+            })),
+        }),
         annotations: READ,
     }, async ({ node, owner, collection, type, rust, astro, limit, offset }) => {
         const r = await reg();
@@ -329,40 +532,47 @@ export function registerMziziTools(server, opts) {
                 ...(astroFile ? { astroFile } : {}),
             };
         });
-        const returned = skip + items.length;
-        return jsonContent({
-            count: items.length,
-            total,
-            offset: skip,
-            hasMore: returned < total,
-            ...(returned < total
-                ? {
-                    nextOffset: returned,
-                    hint: `Call again with offset=${returned}, or narrow with node/owner/collection.`,
-                }
-                : {}),
-            // Present so a caller can distinguish "your filter matched nothing" from "the
-            // registry is empty" — the two look identical in an empty items array, and the
-            // first is a query to rewrite while the second is an outage.
-            ...(registryTotal !== undefined ? { registryTotal } : {}),
-            // How many of the `total` matched rows have a Mzizi Roots (Rust)
-            // implementation. Filter with rust=true to list only those.
-            withRust: payload.meta?.withRust ?? 0,
-            // How many have an Astro implementation. Filter with astro=true to list only those.
-            withAstro: payload.meta?.withAstro ?? 0,
-            items,
-        });
+        const render = (page) => {
+            const returned = skip + page.length;
+            const more = returned < total;
+            return {
+                count: page.length,
+                total,
+                offset: skip,
+                has_more: more,
+                ...(more ? { next_offset: returned } : {}),
+                // camelCase kept for clients written against 0.13 and earlier.
+                hasMore: more,
+                ...(more
+                    ? {
+                        nextOffset: returned,
+                        hint: `Call again with offset=${returned}, or narrow with node/owner/collection.`,
+                    }
+                    : {}),
+                // Present so a caller can distinguish "your filter matched nothing" from "the
+                // registry is empty" — the two look identical in an empty items array, and the
+                // first is a query to rewrite while the second is an outage.
+                ...(registryTotal !== undefined ? { registryTotal } : {}),
+                // How many of the `total` matched rows have a Mzizi Roots (Rust)
+                // implementation. Filter with rust=true to list only those.
+                withRust: payload.meta?.withRust ?? 0,
+                // How many have an Astro implementation. Filter with astro=true to list only those.
+                withAstro: payload.meta?.withAstro ?? 0,
+                items: page,
+            };
+        };
+        return jsonContent(fitToLimit(items, render).result);
     });
     // 4 ─ get_tokens
     server.registerTool(note("get_tokens"), {
         title: "Get design tokens",
-        description: "The Mzizi brand system: 21 colour families (7 minerals, 7 heritage, 7 experimental), semantic colours, typography, spacing, radii and the ecosystem brands. Ask for `colors` to get every colour family in one call.",
-        inputSchema: {
+        description: "The Mzizi brand system: 21 colour families (7 minerals, 7 heritage, 7 experimental), semantic colours, typography, spacing, radii and the ecosystem brands. Ask for `colors` to get every colour family in one call. For text, use each family's `textLight` / `textDark` on the base surface, and `onContainerLight` / `onContainerDark` on its container; never use `hex`, `lightHex` or `darkHex` as a text colour (they are accents).",
+        inputSchema: z.object({
             family: z
-                .string()
+                .string().max(100)
                 .optional()
                 .describe("One of: colors (all 21 colour families at once), minerals, heritage, experimental, semantic, backgrounds, typography, spacing, radii, ecosystem, componentSpecs, accessibility, voiceAndTone, philosophy. Common aliases resolve (status/semanticColors, radius, type/fonts, exp). Omit for everything."),
-        },
+        }),
         annotations: READ,
     }, async ({ family }) => {
         const res = (await reg()).getBrand();
@@ -455,12 +665,12 @@ export function registerMziziTools(server, opts) {
     server.registerTool(note("get_architecture"), {
         title: "Get the architecture",
         description: "The Mzizi DNA double helix — nodes, rungs and strands — with live counts. Pass `node` for one node's covenant, stakeholder and implementation rules.",
-        inputSchema: {
+        inputSchema: z.object({
             node: NUM.int()
                 .positive()
                 .optional()
                 .describe("One node's detail (uncapped)."),
-        },
+        }),
         annotations: READ,
     }, async ({ node }) => {
         const r = await reg();
@@ -470,15 +680,15 @@ export function registerMziziTools(server, opts) {
     server.registerTool(note("get_doctrine"), {
         title: "Get doctrine",
         description: "How to build here: Ubuntu pillars and principles, mzizi conventions, and the AI instruction sets.",
-        inputSchema: {
+        inputSchema: z.object({
             topic: z
                 .enum(["ubuntu-pillars", "ubuntu-principles", "ai-instructions", "conventions"])
                 .describe("Which doctrine to read."),
             name: z
-                .string()
+                .string().max(200)
                 .optional()
                 .describe("For ai-instructions, the name or target to fetch; for conventions, the convention's name. Omit to list."),
-        },
+        }),
         annotations: READ,
     }, async ({ topic, name }) => {
         const r = await reg();
@@ -493,14 +703,18 @@ export function registerMziziTools(server, opts) {
     // 7 ─ get_skills — served from the bundle this Worker ships with
     server.registerTool(note("get_skills"), {
         title: "Get agent skills",
-        description: "List the published Mzizi agent skills, or fetch one in full. Skills are what an agent loads first. Each skill has a category: `dev` (how every agent works in every repo: digital-hygiene and progress-report — load these before any dev work), `design`, `language` or `build`. Pass `category` to get every skill in it in full (e.g. category=dev), or `name` for one skill. Served from the skill files bundled into this server at build time, so they are exactly the text in mzizi-dev/agent-tools at the deployed commit.",
-        inputSchema: {
-            name: z.string().optional().describe("Skill name. Omit to list all."),
+        description: "List the published Mzizi agent skills, or fetch one in full. Skills are what an agent loads first. Each skill has a category: `dev` (how every agent works in every repo: digital-hygiene and progress-report — load these before any dev work), `design`, `language` or `build`. Pass `category` to get every skill in it in full (e.g. category=dev), or `name` for one skill. A skill's answer lists the files it ships beside its SKILL.md (scripts such as hygiene.sh, token stylesheets); pass `name` and `file` to get one file's content. Each skill is also an MCP resource (mzizi://skills/<name>, files at mzizi://skills/<name>/<path>) and a prompt (skill-<name>). Served from the skill files bundled into this server at build time, so they are exactly the text in mzizi-dev/agent-tools at the deployed commit.",
+        inputSchema: z.object({
+            name: z.string().max(200).optional().describe("Skill name. Omit to list all."),
+            file: z
+                .string().max(500)
+                .optional()
+                .describe("With `name`: a file the skill ships, by the path its `files` list gives (e.g. hygiene.sh). Returns that file's content."),
             category: z
                 .enum(SKILL_CATEGORIES)
                 .optional()
                 .describe("Return every skill in this category in full: dev (digital-hygiene, progress-report — for every agent in every repo), design, language or build."),
-        },
+        }),
         annotations: READ,
     }, 
     // No network call, and that is the point. This used to read
@@ -509,7 +723,9 @@ export function registerMziziTools(server, opts) {
     // instructing agents to write into a database column that had been cleared.
     // The Worker now answers from the bundle it was built with: one hop, and a
     // merge is the only way the answer changes.
-    async ({ name, category }) => {
+    async ({ name, category, file }) => {
+        if (file && !name)
+            return toolError("`file` needs `name`: the skill whose file it is.");
         if (name) {
             const skill = BUNDLED_SKILLS.find((s) => s.name === name);
             if (!skill) {
@@ -518,7 +734,14 @@ export function registerMziziTools(server, opts) {
             if (category && skill.category !== category) {
                 return toolError(`Skill "${name}" is in category "${skill.category}", not "${category}".`);
             }
-            return jsonContent({ version: SKILLS_VERSION, ...skill }, "skills");
+            if (file) {
+                const f = skill.files.find((x) => x.path === file);
+                if (!f) {
+                    return toolError(`Skill "${name}" ships no file "${file}". Its files: ${skill.files.map((x) => x.path).join(", ") || "none"}.`);
+                }
+                return jsonContent({ version: SKILLS_VERSION, skill: name, path: f.path, mimeType: f.mimeType, bytes: f.bytes, uri: skillFileUri(name, f.path), encoding: f.encoding, content: f.content }, "skills");
+            }
+            return jsonContent({ version: SKILLS_VERSION, ...skillView(skill) }, "skills");
         }
         if (category) {
             // A category is a working set an agent loads together (category=dev is
@@ -526,7 +749,7 @@ export function registerMziziTools(server, opts) {
             return jsonContent({
                 version: SKILLS_VERSION,
                 category,
-                skills: BUNDLED_SKILLS.filter((s) => s.category === category),
+                skills: BUNDLED_SKILLS.filter((s) => s.category === category).map(skillView),
             }, "skills");
         }
         // The list omits bodies — seven full skills is ~170 kB, and a client
@@ -534,22 +757,31 @@ export function registerMziziTools(server, opts) {
         return jsonContent({
             version: SKILLS_VERSION,
             categories: SKILL_CATEGORIES,
-            skills: BUNDLED_SKILLS.map(({ name: n, category: c, description, source }) => ({
+            skills: BUNDLED_SKILLS.map(({ name: n, category: c, description, source, files }) => ({
                 name: n,
                 category: c,
                 description,
                 source,
+                uri: skillUri(n),
+                files: files.map((f) => f.path),
             })),
         }, "skills");
     });
     // 8 ─ check_accessibility
     server.registerTool(note("check_accessibility"), {
         title: "Check accessibility",
-        description: "Contrast and colour-vision checks against the Mzizi APCA/AAA floor. Computed locally — no network, no upstream dependency.",
-        inputSchema: {
-            foreground: z.string().describe("Foreground colour as #RRGGBB."),
-            background: z.string().describe("Background colour as #RRGGBB."),
-        },
+        description: "The WCAG 2.x contrast ratio of a foreground on a background colour, with the AA-large, AA and AAA verdicts and whether it meets the Mzizi floor of 7:1. Computed locally — no network. It does not compute APCA Lc or simulate colour-vision deficiency; read the Mzizi accessibility doctrine (mzizi_get_tokens family=accessibility) for those rules.",
+        inputSchema: z.object({
+            foreground: z.string().max(16).describe("Foreground colour as #RRGGBB, e.g. #1B1A17."),
+            background: z.string().max(16).describe("Background colour as #RRGGBB, e.g. #FFFFFF."),
+        }),
+        outputSchema: z.object({
+            foreground: z.string(),
+            background: z.string(),
+            contrastRatio: z.number(),
+            passes: z.object({ aaLarge: z.boolean(), aa: z.boolean(), aaa: z.boolean() }),
+            meetsMziziFloor: z.boolean(),
+        }),
         annotations: READ,
     }, async ({ foreground, background }) => {
         const parse = (hex) => {
@@ -593,7 +825,7 @@ export function registerMziziTools(server, opts) {
     server.registerTool(note("report_issue"), {
         title: "Report an issue",
         description: "Report a problem with a component or the registry. It goes to your own issue desk — a Durable Object holding your reports — which reproduces it via fundi, drafts an issue body including what the reproduction actually returned, and logs it to fundi. fundi files the GitHub issue with its proposed fix in it and tracks that issue afterwards, so action 'get' shows where yours got to: filed, picked up, closed. Use 'list' to see your earlier reports and 'retry' to re-attempt one that drafted but could not be logged. Your history is included in each new issue, because a repeated complaint from one reporter is often one bug. Needs sign-in: the desk belongs to your Mzizi console user.",
-        inputSchema: {
+        inputSchema: z.object({
             action: z
                 .enum(["file", "list", "get", "retry"])
                 .default("file")
@@ -603,24 +835,24 @@ export function registerMziziTools(server, opts) {
                 .optional()
                 .describe("Report kind. Required for action 'file'."),
             component: z
-                .string()
+                .string().max(200)
                 .optional()
                 .describe("Component the report concerns."),
             message: z
-                .string()
+                .string().max(20000)
                 .optional()
                 .describe("What happened. Required for action 'file'."),
             severity: z.enum(["low", "medium", "high", "critical"]).optional(),
             skill: z
-                .string()
+                .string().max(100)
                 .optional()
                 .describe("fundi skill to run for the reproduction. fundi never infers a skill from text, so omit this to let the report kind choose one."),
             reportId: z
-                .string()
+                .string().max(200)
                 .optional()
                 .describe("Report id. Required for actions 'get' and 'retry'."),
             limit: z.number().int().min(1).max(100).optional(),
-        },
+        }),
         annotations: WRITE,
     }, async (args) => {
         const desk = opts.desk;
@@ -673,21 +905,21 @@ export function registerMziziTools(server, opts) {
         server.registerTool(note("fundi"), {
             title: "fundi",
             description: "Delegate a task to the fundi agent, or check on one. Submit-and-poll: `submit` returns a task id immediately and never waits for the run. Needs sign-in: fundi runs as your Mzizi console user.",
-            inputSchema: {
+            inputSchema: z.object({
                 action: z.enum(["submit", "task_status", "cancel"]),
                 skill: z
                     .enum(["security-scan", "chaos-run", "a11y-audit", "heal-issue"])
                     .optional()
                     .describe("Required for submit."),
                 instruction: z
-                    .string()
+                    .string().max(20000)
                     .optional()
                     .describe("What fundi should do. Required for submit."),
                 taskId: z
-                    .string()
+                    .string().max(200)
                     .optional()
                     .describe("Required for task_status and cancel."),
-            },
+            }),
             annotations: { ...WRITE, destructiveHint: true },
         }, async ({ action, skill, instruction, taskId }) => {
             if (!f)