@oneentry/mcp-platform-server 0.1.4 → 0.1.5

package/dist/api/build-catalog.js

@@ -1,24 +1,69 @@
 import { createHash } from 'node:crypto';
 import { capSchema, normalizeSchema } from './normalize-schema.js';
+import { ALWAYS_CONFIRM_PREFIXES, OPERATION_NOTES } from './operation-notes.js';
 const API_PREFIX = '/api/admin';
 const METHODS = ['get', 'post', 'put', 'patch', 'delete'];
-const ALWAYS_CONFIRM = [
-    /^\/immutable-settings/,
-    /^\/admins/,
-    /^\/backups/,
-    /^\/modules/,
-    /^\/payments\/webhook/,
-    /^\/auth\/logout\/all-users/,
-    /^\/settings-general/,
-    /^\/system\/captcha-keys/,
-];
-const riskOf = (method) => {
+const ALWAYS_CONFIRM = ALWAYS_CONFIRM_PREFIXES.map((prefix) => new RegExp(`^${prefix.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}`));
+const isGated = (path) => ALWAYS_CONFIRM.some((pattern) => pattern.test(path));
+const riskOf = (method, opId, path) => {
     if (method === 'get') {
         return 'read';
     }
+    if (method === 'post' && OPERATION_NOTES[opId]?.readOnly === true && !isGated(path)) {
+        return 'read';
+    }
     return method === 'delete' ? 'destructive' : 'write';
 };
 const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const jsonTypeOf = (value) => {
+    if (value === null) {
+        return 'null';
+    }
+    if (Array.isArray(value)) {
+        return 'array';
+    }
+    if (typeof value === 'number') {
+        return Number.isInteger(value) ? 'integer' : 'number';
+    }
+    return typeof value;
+};
+const typeFits = (declared, actual) => declared === actual ||
+    (declared === 'number' && actual === 'integer') ||
+    (declared === 'integer' && actual === 'number');
+const markExampleMismatch = (schema, field) => {
+    if (schema['x-loose'] === true || schema.example === undefined || schema.type === undefined) {
+        return undefined;
+    }
+    const actual = jsonTypeOf(schema.example);
+    if (!typeFits(schema.type, actual)) {
+        const message = `declared "${schema.type}", example is ${actual}`;
+        schema['x-example-mismatch'] = message;
+        return `${field} (${message})`;
+    }
+    if (schema.type === 'array' && schema.items?.type !== undefined && schema.items['x-loose'] !== true) {
+        const first = schema.example[0];
+        if (first !== undefined && !typeFits(schema.items.type, jsonTypeOf(first))) {
+            const message = `items declared "${schema.items.type}", example items are ${jsonTypeOf(first)}`;
+            schema['x-example-mismatch'] = message;
+            return `${field} (${message})`;
+        }
+    }
+    return undefined;
+};
+const exampleMismatches = (body) => {
+    const properties = body?.schema.properties;
+    if (!properties) {
+        return [];
+    }
+    const found = [];
+    for (const [name, schema] of Object.entries(properties)) {
+        const mismatch = markExampleMismatch(schema, name);
+        if (mismatch) {
+            found.push(mismatch);
+        }
+    }
+    return found;
+};
 const asString = (value) => typeof value === 'string' && value.trim() !== '' ? value.trim() : undefined;
 const responseSummary = (responses) => {
     if (!isRecord(responses)) {
@@ -60,6 +105,21 @@ const buildParams = (raw, components) => {
     }
     return params;
 };
+const bodyExample = (media) => {
+    if (media['example'] !== undefined) {
+        return media['example'];
+    }
+    const examples = media['examples'];
+    if (!isRecord(examples)) {
+        return undefined;
+    }
+    for (const entry of Object.values(examples)) {
+        if (isRecord(entry) && entry['value'] !== undefined) {
+            return entry['value'];
+        }
+    }
+    return undefined;
+};
 const buildBody = (raw, components) => {
     if (!isRecord(raw)) {
         return undefined;
@@ -76,9 +136,18 @@ const buildBody = (raw, components) => {
     if (!isRecord(media)) {
         return undefined;
     }
+    const schema = capSchema(normalizeSchema(media['schema'], components));
+    const example = bodyExample(media);
+    if (example !== undefined && schema.example === undefined) {
+        schema.example = example;
+    }
+    const description = asString(raw['description']);
+    if (description && schema['x-unresolved'] === true) {
+        schema.description = description.replace(/\s+/g, ' ').slice(0, 240);
+    }
     return {
         contentType,
-        schema: capSchema(normalizeSchema(media['schema'], components)),
+        schema,
         required: raw['required'] === true,
     };
 };
@@ -96,6 +165,8 @@ export const buildCatalog = (params) => {
     const operations = [];
     const foreignPaths = [];
     const withoutOpId = [];
+    const unresolvedBodies = [];
+    const contradictoryExamples = [];
     for (const [fullPath, pathItem] of Object.entries(swagger['paths'])) {
         if (!isRecord(pathItem)) {
             continue;
@@ -118,9 +189,18 @@ export const buildCatalog = (params) => {
             const tags = operation['tags'];
             const tag = (Array.isArray(tags) ? asString(tags[0]) : undefined) ?? 'Other';
             const summary = asString(operation['summary']) ?? asString(operation['description']) ?? '';
-            const risk = riskOf(method);
-            const alwaysConfirm = method !== 'get' && ALWAYS_CONFIRM.some((pattern) => pattern.test(path));
+            const risk = riskOf(method, opId, path);
+            const alwaysConfirm = method !== 'get' && isGated(path);
             const permission = byOpId[opId];
+            const body = buildBody(operation['requestBody'], components);
+            if (body?.schema['x-unresolved'] === true) {
+                unresolvedBodies.push(body.schema.example === undefined ? `${opId} (no example)` : opId);
+            }
+            const mismatches = exampleMismatches(body);
+            if (mismatches.length > 0) {
+                contradictoryExamples.push(`${opId}: ${mismatches.join('; ')}`);
+            }
+            const notes = OPERATION_NOTES[opId];
             const entry = {
                 opId,
                 method,
@@ -132,12 +212,13 @@ export const buildCatalog = (params) => {
                 risk,
                 alwaysConfirm,
                 params: buildParams(operation['parameters'], components),
-                ...(buildBody(operation['requestBody'], components)
-                    ? { body: buildBody(operation['requestBody'], components) }
-                    : {}),
+                ...(body ? { body } : {}),
                 ...(responseSummary(operation['responses'])
                     ? { responseSummary: responseSummary(operation['responses']) }
                     : {}),
+                ...(notes?.note ? { note: notes.note } : {}),
+                ...(notes?.verifyWith ? { verifyWith: notes.verifyWith } : {}),
+                ...(notes?.silentNoOp ? { silentNoOp: notes.silentNoOp } : {}),
                 searchText: '',
             };
             entry.searchText = [opId, method.toUpperCase(), path, tag, summary, permission ?? '']
@@ -156,6 +237,26 @@ export const buildCatalog = (params) => {
         warnings.push(`${String(withoutOpId.length)} operation(s) have no operationId and cannot be called ` +
             `(e.g. ${withoutOpId.slice(0, 3).join(', ')}). Report it against the CMS.`);
     }
+    if (unresolvedBodies.length > 0) {
+        warnings.push(`${String(unresolvedBodies.length)} operation(s) declare a request body whose schema ` +
+            `does not resolve in the document (${unresolvedBodies.slice(0, 5).join(', ')}). ` +
+            'Their body schema is marked "x-unresolved": true — build the body from the example ' +
+            'cms_api_describe returns, and never from the empty schema. Report it against the CMS.');
+    }
+    if (contradictoryExamples.length > 0) {
+        warnings.push(`${String(contradictoryExamples.length)} field(s) carry an example that contradicts their ` +
+            `own declared type (${contradictoryExamples.slice(0, 3).join(' | ')}). ` +
+            'Those fields are marked "x-example-mismatch" and listed by cms_api_describe — ' +
+            'copy the example, not the type. Report it against the CMS.');
+    }
+    const noted = Object.keys(OPERATION_NOTES);
+    const notedButAbsent = noted.filter((opId) => !operations.some((operation) => operation.opId === opId));
+    if (notedButAbsent.length > 0 && notedButAbsent.length <= noted.length / 2) {
+        warnings.push(`${String(notedButAbsent.length)} operation(s) carry a curated behaviour note but are ` +
+            `absent from this catalog (${notedButAbsent.slice(0, 5).join(', ')}). ` +
+            'Either this instance does not expose them, or the note table has gone stale — ' +
+            'the note is not shown for an operation that is not there.');
+    }
     const known = new Set(operations.map((o) => o.opId));
     const missing = Object.keys(byOpId).filter((opId) => !known.has(opId) && !opId.startsWith('Developer') && !opId.startsWith('Content'));
     if (missing.length > 0) {
@@ -173,6 +274,8 @@ export const buildCatalog = (params) => {
                 : 'The bundled permission map was generated from a different platform revision than ' +
                     'this instance runs — update the package if the catalog looks incomplete.'));
     }
+    const mappedPermissions = new Set(Object.values(byOpId));
+    const permissionsWithoutOperation = permissions.filter((permission) => !mappedPermissions.has(permission));
     const knownPermissions = new Set(permissions);
     const orphanPermissions = [
         ...new Set(operations
@@ -191,6 +294,7 @@ export const buildCatalog = (params) => {
         swaggerHash: createHash('sha256').update(rawSwagger).digest('hex').slice(0, 16),
         permissions,
         warnings,
+        coverage: { unexposedOpIds: missing, permissionsWithoutOperation },
         operations,
     };
 };

package/dist/api/catalog.d.ts

@@ -26,6 +26,7 @@ export declare class OperationCatalog {
     get(opId: string): Operation | undefined;
     operations(): readonly Operation[];
     suggest(opId: string, limit?: number): string[];
+    unexposedMatches(query: string, limit?: number): string[];
     search(params: {
         query: string;
         tag?: string;

package/dist/api/catalog.js

@@ -28,7 +28,11 @@ export class OperationCatalog {
         if (catalog.version !== 1) {
             throw new Error(`Unsupported catalog version ${String(catalog.version)}`);
         }
-        this.catalog = { ...catalog, warnings: catalog.warnings ?? [] };
+        this.catalog = {
+            ...catalog,
+            warnings: catalog.warnings ?? [],
+            coverage: catalog.coverage ?? { unexposedOpIds: [], permissionsWithoutOperation: [] },
+        };
         this.byOpId = new Map(catalog.operations.map((o) => [o.opId, o]));
     }
     static permissionMap() {
@@ -70,6 +74,7 @@ export class OperationCatalog {
                         'answers 200 with an OpenAPI document.',
                     ...(auth.error === undefined ? [] : [loginWarning(auth.error)]),
                 ],
+                coverage: { unexposedOpIds: [], permissionsWithoutOperation: [] },
                 operations: [],
             });
         }
@@ -96,6 +101,22 @@ export class OperationCatalog {
             .slice(0, limit)
             .map((entry) => entry.opId);
     }
+    unexposedMatches(query, limit = 5) {
+        const terms = query
+            .toLowerCase()
+            .split(/[\s/.]+/)
+            .filter((term) => term.length > 2);
+        if (terms.length === 0) {
+            return [];
+        }
+        const { unexposedOpIds, permissionsWithoutOperation } = this.catalog.coverage;
+        return [...unexposedOpIds, ...permissionsWithoutOperation]
+            .filter((name) => {
+            const haystack = name.toLowerCase();
+            return terms.some((term) => haystack.includes(term));
+        })
+            .slice(0, limit);
+    }
     search(params) {
         const terms = params.query
             .toLowerCase()

package/dist/api/client.d.ts

@@ -21,6 +21,7 @@ export type CallResult = {
 export declare class RequestBuildError extends Error {
 }
 export declare const normalizeBody: (body: unknown) => unknown;
+export declare const unsupportedBodyFormat: (operation: Operation) => string | undefined;
 export declare const buildUrl: (baseUrl: string, operation: Operation, args: CallArgs) => string;
 export declare class AdminApiClient {
     private readonly baseUrl;

package/dist/api/client.js

@@ -16,6 +16,15 @@ export const normalizeBody = (body) => {
         return body;
     }
 };
+export const unsupportedBodyFormat = (operation) => {
+    const contentType = operation.body?.contentType;
+    if (contentType === undefined || /^application\/(\w[\w.+-]*\+)?json$/.test(contentType)) {
+        return undefined;
+    }
+    return (`Operation ${operation.opId} expects a "${contentType}" request body, and this server ` +
+        'can only send application/json. The call is not executable through MCP — no body ' +
+        'shape will help. Report it to the human and use another route to that instance.');
+};
 export const buildUrl = (baseUrl, operation, args) => {
     let path = operation.path;
     const provided = args.path ?? {};

package/dist/api/normalize-schema.js

@@ -36,7 +36,12 @@ export const normalizeSchema = (node, components, depth = 0, refStack = []) => {
         }
         const target = components[name];
         if (target === undefined) {
-            return { type: 'object', description: `(unresolved ${name})` };
+            return {
+                type: 'object',
+                description: `(unresolved ${name})`,
+                'x-loose': true,
+                'x-unresolved': true,
+            };
         }
         return normalizeSchema(target, components, depth, [...refStack, name]);
     }

package/dist/api/operation-notes.d.ts

@@ -0,0 +1,10 @@
+import type { VerifyWith } from './types.js';
+export interface OperationNote {
+    note?: string;
+    verifyWith?: VerifyWith;
+    silentNoOp?: string;
+    readOnly?: true;
+}
+export declare const ALWAYS_CONFIRM_PREFIXES: readonly string[];
+export declare const OPERATION_NOTES: Readonly<Record<string, OperationNote>>;
+export declare const readOnlyOpIds: () => string[];

package/dist/api/operation-notes.js

@@ -0,0 +1,146 @@
+export const ALWAYS_CONFIRM_PREFIXES = [
+    '/immutable-settings',
+    '/admins',
+    '/backups',
+    '/modules',
+    '/payments/webhook',
+    '/auth/logout/all-users',
+    '/settings-general',
+    '/system/captcha-keys',
+];
+export const OPERATION_NOTES = {
+    AdminProductsController_findAll: {
+        readOnly: true,
+        note: 'Pagination and locale are query parameters, not body fields: pass limit, offset and ' +
+            'langCode in "query". The body is an ARRAY of filter objects — send [] for no filter. ' +
+            'A body of { limit, offset, langCode } answers 400 complaining about langCode, because ' +
+            'the validator is describing the query parameter you did not send.',
+    },
+    AdminProductsController_setStatusForProducts: {
+        silentNoOp: 'The status id goes in "id", not "statusId". With "statusId" the handler reads ' +
+            'undefined, writes NULL over the product status and still answers 201 true. The call ' +
+            'also never re-indexes, so even a correct write stays invisible to ' +
+            'AdminProductsController_findAll. Setting statusId through ' +
+            'AdminProductsController_update is the route that works today.',
+        verifyWith: {
+            opId: 'AdminProductsController_findOne',
+            check: 'statusId',
+            why: 'the call answers 201 true whether or not any row changed',
+        },
+    },
+    AdminAttributesSetsController_create: {
+        note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
+            'locale first: validators.en_US.requiredValidator, not validators.requiredValidator. ' +
+            'A flat map is stored verbatim and read by nobody.',
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'the raw set shows exactly what you wrote, including a flat map that no consumer reads',
+        },
+    },
+    AdminAttributesSetsController_update: {
+        note: 'Inside an attribute, "validators", "localizeInfos" and "listTitles" are keyed by ' +
+            'locale first. A flat map is accepted and stored where nothing reads it.',
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'the raw set shows what you wrote; the projection a site reads shows what it gets',
+        },
+    },
+    AdminAttributesSetsController_updateSchema: {
+        note: 'The body is the schema object itself, never wrapped as { "schema": … }. The wrapped ' +
+            'form answers 200 and replaces the set with a single attribute called "schema". ' +
+            'Locale-keyed rules apply here too.',
+        verifyWith: {
+            opId: 'AdminAttributesSetsController_findOne',
+            check: 'schema[].validators.<locale>',
+            why: 'a wrapped or flat body answers 200 and destroys or discards what you sent',
+        },
+    },
+    AdminFileUploadController_uploadFiles: {
+        note: 'The "template" query parameter is the NUMERIC id of a /template-previews record, not ' +
+            'a boolean flag. A fresh instance has no such records, and an upload without a valid ' +
+            'template id stores the file with no preview and reports no error.',
+    },
+    AdminMenusController_create: {
+        note: 'Create the menu with an empty pagesIds, then attach pages with AdminMenusController_update. ' +
+            'A non-empty pagesIds on create answers 500 (null value in column "page_id"). That 500 is ' +
+            'known — do not report it as an unexplained server failure.',
+    },
+    AdminFormsController_create: {
+        note: 'Send the payload wrapped under "newForm". The form "type" is missing from the schema but ' +
+            'is accepted and persisted: order | sign_in_up | collection | data | rating. A contact ' +
+            'form is "data". Omit it and the form is created with type null.',
+        verifyWith: {
+            opId: 'AdminFormsController_findAll',
+            check: 'type',
+            why: 'the field is absent from the schema, so an omitted type is not reported as missing',
+        },
+    },
+    AdminFormsController_update: {
+        note: '"formModuleConfigs" is a full replacement list, not a patch. Omitting it deletes every ' +
+            'module binding of the form AND the submissions recorded against those bindings, and the ' +
+            'call still answers 200 true. Read the form first and send its current formModuleConfigs ' +
+            'back unless changing them is the point. This is also the only operation that creates a ' +
+            'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers.',
+        verifyWith: {
+            opId: 'AdminFormsController_findOne',
+            check: 'formModuleConfigs',
+            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included',
+        },
+    },
+    AdminFormDataController_create: {
+        note: 'A submission needs formIdentifier, formModuleConfigId, moduleEntityIdentifier and ' +
+            'locale-keyed formData. formModuleConfigId is the id of a module binding, which only ' +
+            'AdminFormsController_update creates and only AdminFormsController_findOne reports, under ' +
+            'formModuleConfigs[].id — a freshly created form has none and accepts nothing. The server ' +
+            'joins the config back to its form and compares identifiers, so a config id belonging to ' +
+            'another form, or to no form, answers 400 "Incorrect formIdentifier for provided config": ' +
+            'the message names formIdentifier, the wrong field is usually the config id. Checks run ' +
+            'fields first, then the form type, then the config, so a field error arriving first does ' +
+            'not mean the config is optional. A form with type null fails earlier with "Form has ' +
+            'incorrect type". Field validation is wired into the Content API only: through the Admin ' +
+            'API a missing required field is stored rather than rejected, so a submission accepted ' +
+            'here does not prove a visitor\'s submission would pass.',
+        verifyWith: {
+            opId: 'AdminFormDataController_findByFormMarker',
+            check: 'the submission you sent',
+            why: 'the stored submission is the only proof the binding it names is the intended one',
+        },
+    },
+    AdminPagesController_update: {
+        note: 'Omitting parentId does not leave the parent alone — it moves the page to the root and ' +
+            'decrements the former parent\'s childrenCount. Read the page first and send parentId ' +
+            'back unchanged unless you mean to re-parent it.',
+        verifyWith: {
+            opId: 'AdminPagesController_findOne',
+            check: 'parentId',
+            why: 'an omitted parentId is applied as "move to root", and the update still answers 200',
+        },
+    },
+    AdminBlocksController_update: {
+        note: 'Omitting blockPages detaches the block from every page it was on. Read the block first ' +
+            'and send its current page list back unless you mean to change it.',
+        verifyWith: {
+            opId: 'AdminBlocksController_findOne',
+            check: 'blockPages',
+            why: 'an omitted blockPages is applied as "detach everything", and the update answers 200',
+        },
+    },
+    AdminProductsController_countAll: { readOnly: true },
+    AdminProductsController_findByIds: { readOnly: true },
+    AdminProductsController_findAllByWithOutCategory: { readOnly: true },
+    AdminProductsController_findAllByCategoryIdForAdmin: { readOnly: true },
+    AdminProductsController_countByCategoryId: { readOnly: true },
+    AdminProductsController_countByCategoryMarker: { readOnly: true },
+    AdminUsersController_findAllByConditions: { readOnly: true },
+    AdminUsersController_search: { readOnly: true },
+    AdminFormDataController_findByFormMarker: { readOnly: true },
+    AdminBlocksController_findCartComplementProductsByBody: { readOnly: true },
+    AdminBlocksController_findCartSimilarProductsByBody: { readOnly: true },
+    AdminBlocksController_findWishlistSimilarProductsByBody: { readOnly: true },
+    AdminUserGroupsController_getGroupRoutesWithPermissions: { readOnly: true },
+};
+export const readOnlyOpIds = () => Object.entries(OPERATION_NOTES)
+    .filter(([, note]) => note.readOnly === true)
+    .map(([opId]) => opId);

package/dist/api/types.d.ts

@@ -1,5 +1,10 @@
 export type HttpMethod = 'get' | 'post' | 'put' | 'patch' | 'delete';
 export type RiskLevel = 'read' | 'write' | 'destructive';
+export interface VerifyWith {
+    opId: string;
+    check: string;
+    why: string;
+}
 export interface OperationParam {
     name: string;
     location: 'path' | 'query' | 'header';
@@ -13,6 +18,7 @@ export interface JsonSchema {
     format?: string;
     description?: string;
     example?: unknown;
+    default?: unknown;
     enum?: unknown[];
     items?: JsonSchema;
     properties?: Record<string, JsonSchema>;
@@ -20,6 +26,8 @@ export interface JsonSchema {
     'x-loose'?: boolean;
     'x-source-type'?: string;
     'x-truncated'?: boolean;
+    'x-example-mismatch'?: string;
+    'x-unresolved'?: boolean;
 }
 export interface Operation {
     opId: string;
@@ -38,8 +46,15 @@ export interface Operation {
         required: boolean;
     };
     responseSummary?: string;
+    note?: string;
+    verifyWith?: VerifyWith;
+    silentNoOp?: string;
     searchText: string;
 }
+export interface CatalogCoverage {
+    unexposedOpIds: string[];
+    permissionsWithoutOperation: string[];
+}
 export interface Catalog {
     version: 1;
     builtAt: string;
@@ -47,5 +62,6 @@ export interface Catalog {
     swaggerHash: string;
     permissions: string[];
     warnings: string[];
+    coverage: CatalogCoverage;
     operations: Operation[];
 }

package/dist/knowledge/ru-en-terms.d.ts

@@ -0,0 +1 @@
+export declare const withEnglishTerms: (query: string) => string;

package/dist/knowledge/ru-en-terms.js

@@ -0,0 +1,67 @@
+const RU_EN = {
+    атрибут: 'attribute',
+    блок: 'block',
+    валидатор: 'validator',
+    вложен: 'nested',
+    выгрузк: 'export',
+    групп: 'group',
+    доступ: 'permission access',
+    заказ: 'order',
+    запрос: 'request',
+    значени: 'value',
+    изображени: 'image file',
+    импорт: 'import',
+    индекс: 'index',
+    каталог: 'catalogue catalog',
+    картинк: 'image file',
+    категори: 'page category',
+    локал: 'locale',
+    маркер: 'marker identifier',
+    меню: 'menu',
+    модул: 'module',
+    набор: 'set',
+    настройк: 'settings',
+    ошибк: 'error',
+    пагинац: 'pagination limit offset',
+    парамет: 'parameter',
+    перевод: 'localization locale',
+    подтвержд: 'confirm',
+    поиск: 'search',
+    позиц: 'position',
+    польз: 'user',
+    превью: 'preview',
+    прав: 'permission',
+    продукт: 'product',
+    сортиров: 'sort order',
+    ссылк: 'link',
+    статус: 'status',
+    страниц: 'page',
+    схем: 'schema',
+    товар: 'product',
+    тип: 'type',
+    файл: 'file upload',
+    фильтр: 'filter',
+    форм: 'form',
+    шаблон: 'template',
+    язык: 'language locale',
+};
+const STEMS = Object.keys(RU_EN).sort((a, b) => b.length - a.length);
+export const withEnglishTerms = (query) => {
+    const lower = query.toLowerCase();
+    if (!/[а-яё]/.test(lower)) {
+        return query;
+    }
+    const added = new Set();
+    for (const word of lower.split(/[^\p{L}\p{N}]+/u)) {
+        if (word === '') {
+            continue;
+        }
+        const stem = STEMS.find((candidate) => word.startsWith(candidate));
+        if (stem) {
+            for (const term of RU_EN[stem]?.split(' ') ?? []) {
+                added.add(term);
+            }
+        }
+    }
+    return added.size > 0 ? `${query} ${[...added].join(' ')}` : query;
+};

package/dist/knowledge/search.js

@@ -1,4 +1,5 @@
 import MiniSearch from 'minisearch';
+import { withEnglishTerms } from './ru-en-terms.js';
 const REPO_WEIGHT = { mcp: 1.6, back: 1, front: 0.9 };
 const KIND_WEIGHT = {
     docs: 1.15,
@@ -69,7 +70,7 @@ export class KnowledgeIndex {
     }
     search(query, limit = 8) {
         const terms = query.split(/\s+/).filter((t) => t.length > 1);
-        const raw = this.mini.search(meaningfulQuery(query));
+        const raw = this.mini.search(withEnglishTerms(meaningfulQuery(query)));
         const hits = [];
         for (const result of raw) {
             const chunk = this.byId.get(String(result.id));

package/dist/tools/api-call.js

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { AuditLog } from '../api/audit.js';
-import { buildUrl, normalizeBody, RequestBuildError } from '../api/client.js';
+import { buildUrl, normalizeBody, RequestBuildError, unsupportedBodyFormat, } from '../api/client.js';
 import { checkLevel, decide } from '../api/policy.js';
 import { shapeResponse, summarizeTarget } from '../api/shape.js';
 import { errorResult, jsonResult } from './result.js';
@@ -40,6 +40,10 @@ export const registerApiCall = (server, getSession) => {
                 hint: 'Operation ids come from cms_api_search — do not construct them by hand.',
             });
         }
+        const formatDenial = unsupportedBodyFormat(operation);
+        if (formatDenial) {
+            return errorResult(formatDenial, { opId, contentType: operation.body?.contentType });
+        }
         const normalizedBody = normalizeBody(body);
         const args = {
             ...(path ? { path } : {}),
@@ -141,6 +145,15 @@ export const registerApiCall = (server, getSession) => {
             status: result.status,
             truncated: shaped.truncated,
             body: shaped.body,
+            ...(operation.verifyWith
+                ? {
+                    verifyWith: operation.verifyWith,
+                    next: `This write is not confirmed by its status. Read it back with ` +
+                        `${operation.verifyWith.opId} and check "${operation.verifyWith.check}" ` +
+                        'before reporting success.',
+                }
+                : {}),
+            ...(operation.silentNoOp ? { silentNoOp: operation.silentNoOp } : {}),
         });
     });
 };

package/dist/tools/api-discovery.js

@@ -1,5 +1,56 @@
 import { z } from 'zod';
+import { unsupportedBodyFormat } from '../api/client.js';
 import { errorResult, jsonResult } from './result.js';
+const sampleValue = (schema, example) => {
+    if (example !== undefined) {
+        return example;
+    }
+    if (schema.example !== undefined) {
+        return schema.example;
+    }
+    if (schema.enum && schema.enum.length > 0) {
+        return schema.enum[0];
+    }
+    switch (schema.type) {
+        case 'number':
+        case 'integer':
+            return 0;
+        case 'boolean':
+            return false;
+        case 'array':
+            return [];
+        case 'object':
+            return {};
+        default:
+            return `<${schema['x-source-type'] ?? schema.type ?? 'value'}>`;
+    }
+};
+const isWorthShowing = (param) => param.required ||
+    param.example !== undefined ||
+    param.schema.example !== undefined ||
+    param.schema.default !== undefined;
+const argsFor = (params, location, filter) => {
+    const out = {};
+    for (const param of params) {
+        if (param.location !== location || !filter(param)) {
+            continue;
+        }
+        out[param.name] = sampleValue(param.schema, param.example);
+    }
+    return out;
+};
+const callExample = (operation) => {
+    const path = argsFor(operation.params, 'path', () => true);
+    const query = argsFor(operation.params, 'query', isWorthShowing);
+    return {
+        opId: operation.opId,
+        ...(Object.keys(path).length > 0 ? { path } : {}),
+        ...(Object.keys(query).length > 0 ? { query } : {}),
+        ...(operation.body?.schema.example !== undefined
+            ? { body: operation.body.schema.example }
+            : {}),
+    };
+};
 export const registerApiDiscovery = (server, deps) => {
     const { catalog } = deps;
     server.registerTool('cms_api_search', {
@@ -22,10 +73,16 @@ export const registerApiDiscovery = (server, deps) => {
             ...(limit ? { limit } : {}),
         });
         if (hits.length === 0) {
+            const unexposed = catalog.unexposedMatches(query);
             return jsonResult({
                 hits: [],
                 tags: [...new Set(catalog.operations().map((o) => o.tag))].sort(),
-                hint: 'Nothing matched. Try a bare entity name, or filter by one of the tags listed here.',
+                ...(unexposed.length > 0 ? { knownButNotExposed: unexposed } : {}),
+                hint: unexposed.length > 0
+                    ? 'Nothing matched in this catalog, but the platform does know the names under ' +
+                        '"knownButNotExposed" — this instance simply does not serve them, so no path ' +
+                        'you construct will reach them. Do not guess URLs: report them as unavailable here.'
+                    : 'Nothing matched. Try a bare entity name, or filter by one of the tags listed here.',
             });
         }
         return jsonResult({
@@ -35,7 +92,7 @@ export const registerApiDiscovery = (server, deps) => {
     });
     server.registerTool('cms_api_describe', {
         title: 'Describe an Admin API operation',
-        description: 'Full detail for one operation: path and query parameters, request-body schema, required permission, risk level, and whether it is permanently confirm-gated. Fields marked "x-loose": true could not be converted to a JSON Schema type — trust their example, not their type.',
+        description: 'Full detail for one operation: a ready-to-copy "example" call, path and query parameters, request-body schema, required permission, risk level, and whether it is permanently confirm-gated. Fields marked "x-loose": true could not be converted to a JSON Schema type — trust their example, not their type. Where the operation is known to answer success without doing the work, "silentNoOp" and "verifyWith" say so and name the read that proves it.',
         inputSchema: {
             opId: z.string().min(1).describe('Operation id from cms_api_search, e.g. "AdminPagesController_findAllRoot".'),
         },
@@ -43,18 +100,28 @@ export const registerApiDiscovery = (server, deps) => {
     }, ({ opId }) => {
         const operation = catalog.get(opId);
         if (!operation) {
+            const unexposed = catalog.unexposedMatches(opId);
             return errorResult(`Unknown opId "${opId}".`, {
                 didYouMean: catalog.suggest(opId),
-                hint: 'Operation ids come from cms_api_search — do not construct them by hand.',
+                ...(unexposed.length > 0 ? { knownButNotExposed: unexposed } : {}),
+                hint: unexposed.length > 0
+                    ? 'The platform knows this name, but this instance does not serve the operation, ' +
+                        'so it cannot be called from here by any path. Report it as unavailable.'
+                    : 'Operation ids come from cms_api_search — do not construct them by hand.',
             });
         }
-        const loose = [
-            ...(operation.body?.schema.properties
-                ? Object.entries(operation.body.schema.properties)
-                    .filter(([, schema]) => schema['x-loose'] === true)
-                    .map(([name, schema]) => ({ field: name, sourceType: schema['x-source-type'] }))
-                : []),
-        ];
+        const formatDenial = unsupportedBodyFormat(operation);
+        const properties = operation.body?.schema.properties;
+        const loose = properties
+            ? Object.entries(properties)
+                .filter(([, schema]) => schema['x-loose'] === true)
+                .map(([name, schema]) => ({ field: name, sourceType: schema['x-source-type'] }))
+            : [];
+        const mismatched = properties
+            ? Object.entries(properties)
+                .filter(([, schema]) => schema['x-example-mismatch'] !== undefined)
+                .map(([name, schema]) => ({ field: name, problem: schema['x-example-mismatch'] }))
+            : [];
         return jsonResult({
             opId: operation.opId,
             method: operation.method.toUpperCase(),
@@ -66,12 +133,41 @@ export const registerApiDiscovery = (server, deps) => {
             risk: operation.risk,
             alwaysConfirm: operation.alwaysConfirm,
             params: operation.params,
+            paramsByLocation: {
+                path: operation.params.filter((p) => p.location === 'path').map((p) => p.name),
+                query: operation.params.filter((p) => p.location === 'query').map((p) => p.name),
+            },
             body: operation.body ?? null,
+            example: callExample(operation),
             looseFields: loose,
+            ...(mismatched.length > 0
+                ? {
+                    exampleMismatches: mismatched,
+                    exampleMismatchHint: 'These fields declare one type and give an example of another. The example is ' +
+                        'the contract — the instance accepts what the example shows.',
+                }
+                : {}),
+            ...(operation.note ? { note: operation.note } : {}),
+            ...(operation.silentNoOp ? { silentNoOp: operation.silentNoOp } : {}),
+            ...(operation.verifyWith ? { verifyWith: operation.verifyWith } : {}),
+            ...(operation.body?.schema['x-unresolved'] === true
+                ? {
+                    bodySchemaUnresolved: 'The document does not resolve this body schema, so the empty "properties" ' +
+                        'above means "unknown", not "no fields". Build the body from "example"; ' +
+                        'if there is none, ask the human rather than guessing.',
+                }
+                : {}),
+            ...(formatDenial ? { notExecutable: formatDenial } : {}),
             responseSummary: operation.responseSummary ?? null,
-            next: operation.risk === 'read'
-                ? 'Call it with cms_api_call { opId, path, query }.'
-                : 'Search the knowledge base with cms_docs_search for this entity, then call cms_api_call with dryRun: true first.',
+            next: formatDenial
+                ? 'Do not call this operation — report it as unavailable through MCP.'
+                : operation.risk === 'read'
+                    ? 'Call it with cms_api_call, copying the "example" above.'
+                    : operation.verifyWith
+                        ? 'Search the knowledge base with cms_docs_search for this entity, call cms_api_call ' +
+                            `with dryRun: true first, and afterwards read the result back with ` +
+                            `${operation.verifyWith.opId} — a success status is not evidence here.`
+                        : 'Search the knowledge base with cms_docs_search for this entity, then call cms_api_call with dryRun: true first.',
         });
     });
 };

package/dist/tools/docs.js

@@ -16,7 +16,10 @@ export const registerDocs = (server, deps) => {
         if (hits.length === 0) {
             return jsonResult({
                 hits: [],
-                hint: 'Nothing matched. Try a module name (menus, orders, blocks, attributes) or an entity field name.',
+                hint: 'Nothing matched. The knowledge base is written in English — ask in English, even ' +
+                    'when the conversation is not. Try a module name (menus, orders, blocks, ' +
+                    'attributes) or an entity field name. An empty result means this query found ' +
+                    'nothing, not that the CMS has no documentation for it.',
             });
         }
         return jsonResult({

package/dist/tools/guide.js

@@ -1,3 +1,4 @@
+import { ALWAYS_CONFIRM_PREFIXES } from '../api/operation-notes.js';
 import { textResult } from './result.js';
 const TAG_LIMIT = 24;
 export const renderGuide = (deps) => {
@@ -50,8 +51,19 @@ export const renderGuide = (deps) => {
         '## Hard limits',
         '',
         '- Admin API only. The Content and Developer APIs are deliberately not exposed.',
-        '- `immutable-settings`, `admins`, `backups`, `modules`, `payments/webhook`, `settings-general`,',
-        '  `system/captcha-keys` and `auth/logout/all-users` are permanently confirm-gated.',
+        `- Mutations under ${ALWAYS_CONFIRM_PREFIXES.map((p) => `\`${p}\``).join(', ')} are`,
+        '  permanently confirm-gated, at every allow level.',
+        '- **Request bodies are sent as JSON only.** An operation that declares another format —',
+        '  file upload is `multipart/form-data` — cannot be called through this server at all.',
+        '  `cms_api_describe` marks it `notExecutable`; no body shape will help. Upload files',
+        '  outside MCP and read `mcp/docs/api/files-and-uploads` first, because doing so gives up',
+        '  the confirmations, permission checks and `dryRun` this server provides.',
+        '- **The knowledge base is written in English.** Search it in English whatever language the',
+        '  conversation is in; an empty result is a failed query, not a missing document.',
+        '- A success status is not evidence that the write landed. Where an operation is known to',
+        '  answer success without doing the work, `cms_api_describe` says so under `silentNoOp` and',
+        '  names the read that proves it under `verifyWith`. Verify with the read the *consumer*',
+        '  uses, not the one you wrote to.',
         '- Responses are capped; overflow is reported as `_truncated`. Narrow the query instead.',
         ...(catalog.catalog.warnings.length > 0
             ? ['', '## Warnings', '', ...catalog.catalog.warnings.map((w) => `- ${w}`)]

package/dist/tools/whoami.js

@@ -26,6 +26,11 @@ export const registerWhoami = (server, getSession) => {
                 swaggerHash: catalog.catalog.swaggerHash,
                 builtAt: catalog.catalog.builtAt,
                 knownPermissions: catalog.catalog.permissions.length,
+                coverage: {
+                    unexposedOperations: catalog.catalog.coverage.unexposedOpIds.length,
+                    permissionsWithoutOperation: catalog.catalog.coverage.permissionsWithoutOperation.length,
+                    hint: 'This catalog is what the instance serves, not everything the platform has. When cms_api_search finds nothing, it reports whether the name exists but is unexposed — trust that over constructing a path.',
+                },
                 warnings: catalog.catalog.warnings,
             },
             knowledge: {

package/knowledge/operating-rules.md

@@ -1,25 +1,23 @@
 # Operating rules for the OneEntry Admin API
 
-Read this before your first write. Every rule here has broken a real payload, and each one links to the document that explains it in full.
-
-These rules are short on purpose. When one of them applies to what you are about to do, follow the pointer before you build the body.
+Read this before your first write. Every rule here has broken a real payload; each links to the document explaining it in full. When one applies to what you are about to do, follow the pointer before you build the body.
 
 → `mcp/docs/server/doc-map` · `mcp/docs/server/payload-conventions`
 
 ## The loop you must follow
 
 1. `cms_guide` once, at the start.
-2. `cms_docs_search` for the entity you are about to touch — **before** you write a payload, not after a 400.
-3. `cms_api_search` to find the operation, then `cms_api_describe` for its exact shape.
+2. `cms_docs_search` for the entity you are about to touch — **before** the payload, not after a 400.
+3. `cms_api_search` for the operation, then `cms_api_describe` for its shape.
 4. `cms_api_call` with `dryRun: true` for anything that mutates, then again with the confirm token if one was issued.
 
-Never invent a path, an operation id or a body key. `cms_api_search` is the only authority on what exists; the documents are the authority on what the values mean.
+Never invent a path, an operation id or a body key. `cms_api_search` is the only authority on what exists.
 
 ## Trust the example not the type
 
-The OpenAPI document this catalog is built from contains field types that are not JSON Schema types. `cms_api_describe` normalises what it can and marks the rest `"x-loose": true`, with the original under `x-source-type`.
+The API document carries field types that are not JSON Schema types. `cms_api_describe` normalises what it can and marks the rest `"x-loose": true`.
 
-For a loose field, **the `example` is the contract**. Copy its shape. Client-side validation of your body is advisory only — the instance is the real validator, so a call is never blocked because a loose field could not be checked.
+For those, **the `example` is the contract** — copy its shape. Validation here is advisory; the instance is the real validator, so a call is never blocked over a field we could not check. A field flagged `x-example-mismatch` contradicts its own type, and the example wins there too.
 
 → `mcp/docs/server/cms-api-describe#loose-fields`
 
@@ -31,7 +29,7 @@ Titles and descriptive content live under `localizeInfos`, keyed by locale code:
 { "localizeInfos": { "en_US": { "title": "Summer sale" } } }
 ```
 
-Required when creating a product, and effectively required on pages. Do not hardcode `en_US`: read the active locale codes from the instance first, and write every locale the instance has active if the content is meant to be visible in all of them.
+Required on a product, effectively required on a page. Do not hardcode `en_US`: read the active locales with `AdminLocalesController_findAllActive` and write every one the content is meant to appear in.
 
 → `mcp/docs/api/locales`
 
@@ -43,79 +41,90 @@ Required when creating a product, and effectively required on pages. Do not hard
 { "attributesSets": { "en_US": { "string_id42": "SKU-1" } } }
 ```
 
-The inner key is `<attribute type>_id<attribute id>`, taken from the attribute set the entity belongs to. Read the set before you build the body.
-
-A flat single-level map is accepted and stored empty. The call answers 201 and the attributes are silently missing, so always read the entity back by id after creating it.
+The inner key is `<attribute type>_id<attribute id>`, read from the entity's attribute set. A flat one-level map is accepted, answers 201 and stores nothing — so read the entity back by id after creating it.
 
 → `mcp/docs/api/attribute-sets`
 
 ## Positions are lexorank or numeric depending on the endpoint
 
-Ordering is a lexorank **string** on parent-scoped Admin operations, and a **number** on flat lists and the Content API. Never sort a lexorank value numerically, and never reorder by patching the field directly — use the dedicated position operations of that entity.
+Ordering is a lexorank **string** on parent-scoped Admin operations and a **number** on flat lists and the Content API. Never sort a lexorank numerically, and never reorder by patching the field — use that entity's position operation.
 
 → `mcp/docs/server/payload-conventions#position-is-a-lexorank-string-or-a-number`
 
 ## A read straight after a write can lag
 
-Reading an entity **by id** shows your write immediately. List and search responses may not, for a few seconds.
+Reading an entity **by id** shows your write immediately. Lists and searches may not, for a few seconds.
 
-If a list does not yet show what you just created, re-read by id to confirm it exists. **Never repeat the write** — you will create a duplicate that consumes instance quota and has to be cleaned up by hand.
+If a list does not show what you just created, re-read by id. **Never repeat the write** — you get a duplicate that consumes quota and has to be cleaned up by hand. And never swallow a failed read into an empty result: "empty" and "malformed" then look alike, and the next run recreates everything.
 
-## Prefer marker over id
+## A 200 means accepted not applied
+
+Several endpoints take the body as one opaque value, so a wrong **shape** is stored as happily as a right one and the answer is still `200`.
+
+Confirm a write by its effect, and **through the read its consumer uses**. The raw record echoes your input back, wrong shape included, while the projection a site receives shows nothing — verifying through the endpoint you wrote to proves little.
+
+→ `mcp/docs/api/silent-no-ops`
+
+## An omitted field can mean clear it
+
+Most updates merge. A few apply an omitted field as **"set it to nothing"**, and still answer `200`: a page without `parentId` moves to the root, a block without `blockPages` detaches from every page, a menu item without its parent reference flattens, a user without `formData` loses it.
+
+Products, `generalTypeId` and `attributeSetId` merge, so "PUT always replaces" is the wrong lesson. Read, change what you meant to, send it back whole — then check the fields that were **not** in your body.
 
-Blocks, forms, menus, templates, general types and modules are addressed by a `marker` or `identifier` that is stable across instances. A numeric `id` is not: an id taken from one instance is meaningless on another, and `404 Not found` on an id you were given is usually that mistake.
+→ `mcp/docs/server/payload-conventions#an-omitted-field-can-mean-clear-it`
 
-Where an operation accepts either, use the marker.
+## Prefer marker over id
+
+Blocks, forms, menus, templates, general types and modules are addressed by a `marker` or `identifier` stable across instances. A numeric `id` is not, and a `404` on an id you were given is usually that. Where an operation accepts either, use the marker.
 
 ## Baseline data already exists do not recreate it
 
-Every instance arrives populated: a guest user group with its content-API permissions, the admin modules, the general types, the attribute set types and field types, the locales, the dynamic block types and their default templates, and the singleton settings records.
+Every instance arrives populated: user groups, modules, general types, attribute set and field types, locales, block types with their default templates, the singleton settings.
+
+**List first, create second.** Some duplicates fail loudly, which is harmless. The dangerous ones — user groups, modules, attribute set types, settings — **succeed silently**.
 
-**List first, create second.** Some duplicates fail loudly, which is harmless. The dangerous ones — user groups, modules, attribute set types, settings records — **succeed silently** and leave a shadow record that nothing references.
+Two lists are the exception and start **empty**: product statuses and template previews. Nothing seeds them, nothing reports their absence, and without them no product is sellable and no upload gets a preview. There, create.
 
 → `mcp/docs/api/baseline-data`
 
 ## Never touch these without a human saying so
 
-Mutations under `immutable-settings`, `admins`, `backups`, `modules`, `payments/webhook`, `settings-general`, `system/captcha-keys` and `auth/logout/all-users` are permanently confirm-gated by this server, at every allow level.
+Mutations on the instance's own configuration — admins, modules, backups, settings — are permanently confirm-gated at every allow level. `cms_guide` prints the exact list.
 
-The gate is not a suggestion. State what you intend to change, show the human the `target` the dry run returned, and wait for them to say yes in this conversation.
+The gate is not a suggestion. State what you intend to change, show the human the dry run's `target`, and wait for a yes here.
 
 → `mcp/docs/server/allow-levels#paths-that-are-always-confirm-gated`
 
 ## Permissions are checked before the request is sent
 
-Each operation declares the permission it requires, and this server refuses locally when the authenticated admin does not hold it. Nothing is sent, so nothing changed.
-
-A permission refusal means **ask for the grant** and stop. Retrying cannot succeed, and neither can a different operation that needs the same permission.
+Each operation declares the permission it needs, and this server refuses locally when the admin does not hold it. Nothing is sent, so nothing changed. A refusal means **ask for the grant** and stop — no retry and no sibling operation gets past it.
 
 → `mcp/docs/api/admins-and-permissions`
 
 ## Truncated responses are deliberate
 
-Large responses come back with a `_truncated` envelope reporting what was shown and what the total was. That is this server capping what it hands you, not the API limiting itself.
-
-Do not retry hoping for more. Narrow the request with the operation's own `limit`, `offset` and filter parameters.
+A large response comes back with a `_truncated` envelope reporting what was shown and what the total was. That is this server capping what it hands you, not the API. Do not retry hoping for more — narrow the request with the operation's own `limit`, `offset` and filters.
 
 → `mcp/docs/server/response-shaping`
 
 ## Operations with a single supported path
 
-For the calls below, one route works and the obvious alternative does not. Use the supported one directly — a different body or a retry on the other route will not help.
+One route works and the obvious alternative does not. Use it directly.
 
-- **Create a form** — send the payload wrapped in `newForm`. The OpenAPI document shows the fields unwrapped; the wrapped form is the one the endpoint accepts.
-- **Update a product** — always include `blocks` (send `blocks: []` when you have nothing to set), and never include `forms`.
-- **Read locale codes** — use `AdminLocalesController_findAllActive`.
-- **List products** — the list operation is `POST /products/all`; there is no `GET /products`.
-- **Export operations** — `orders.export`, `payments.export` and `users.export` are not grantable on current instances. Treat them as unavailable and tell the human rather than retrying.
+- **Create a form** — wrap in `newForm`, with `type` (`data` for a contact form) though the schema omits it.
+- **Replace an attribute set schema** — send the schema object itself. Wrapped as `{ "schema": … }` it answers 200 and destroys it.
+- **Update a product** — include `blocks` (`[]` if nothing to set), never `forms`.
+- **Create a menu** — with `pagesIds: []`, attaching pages later. Non-empty on create answers 500.
+- **Set a product status** — `statusId` in the product update. Bulk `set-status` takes it in a field named `id`, and given `statusId` it nulls the status and answers `201 true`.
 
-If a call outside this list answers 5xx, stop and report it with the operation id and the request you sent. Do not retry it with a modified body.
+## List products and other calls whose input is split
 
-## Where to look next
+`POST /products/all` is the only way to list products, and its input is split: **paging and `langCode` go in the query, the body is an array of filters** — `[]` for none. Sent in the body they are ignored, and the 400 blames `langCode` for a value you never sent.
+
+Copy `example` from `cms_api_describe` whole: separate `params` and `body` schemas do not assemble into an obvious call, and `example` is already one.
 
-With the operation hints removed from `cms_api_describe`, `cms_docs_search` and the map below are how you find anything.
+A 5xx outside these two lists means stop and report it, with the operation id and the request.
+
+## Where to look next
 
-- `mcp/docs/server/doc-map` — every document, with when to read it
-- `mcp/docs/server/payload-conventions` — the rules above, in full
-- `mcp/docs/api/baseline-data` — what already exists on your instance
-- `mcp/docs/server/errors-and-refusals` — what a specific error means and what to do next
+`mcp/docs/server/doc-map` lists every document with a reason to read it. The corpus is **English** — search it in English whatever language you answer in.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "MIT",
   "type": "module",
@@ -50,6 +50,7 @@
     "start": "node dist/bin/cli.js",
     "dev": "tsx src/bin/cli.ts",
     "sync:permissions": "tsx build/sync-permissions.ts",
+    "docs:audit": "tsx build/docs-audit.ts",
     "publish:knowledge": "node -e \"console.error('REFUSED: the knowledge repository is hand-authored. Bulk-copying internal docs into it is prohibited.'); process.exit(1)\"",
     "lint": "eslint \"{src,build,__tests__}/**/*.ts\"",
     "test": "vitest run",