@oneentry/mcp-platform-server 0.1.7 → 0.1.9

package/data/permissions.json

@@ -214,6 +214,7 @@
     "AdminTemplatePreviewsController_update": "settings.templatePreview.update",
     "AdminTemplatePreviewsController_remove": "settings.templatePreview.delete",
     "AdminTemplatePreviewsController_updateAttributeSetPosition": "settings.templatePreview.changePositions",
+    "AdminTemplatePreviewsController_regenerate": "settings.templatePreview.update",
     "AdminTemplatesController_create": "settings.templates.create",
     "AdminTemplatesController_update": "settings.templates.update",
     "AdminTemplatesController_remove": "settings.templates.delete",

package/dist/api/build-catalog.js

@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { phantomPathParams } from './client.js';
 import { capSchema, normalizeSchema } from './normalize-schema.js';
 import { ALWAYS_CONFIRM_PREFIXES, OPERATION_NOTES } from './operation-notes.js';
 const API_PREFIX = '/api/admin';
@@ -167,6 +168,7 @@ export const buildCatalog = (params) => {
     const withoutOpId = [];
     const unresolvedBodies = [];
     const contradictoryExamples = [];
+    const undeliverableParams = [];
     for (const [fullPath, pathItem] of Object.entries(swagger['paths'])) {
         if (!isRecord(pathItem)) {
             continue;
@@ -225,6 +227,10 @@ export const buildCatalog = (params) => {
             entry.searchText = [opId, method.toUpperCase(), path, tag, summary, permission ?? '']
                 .join(' ')
                 .toLowerCase();
+            const phantom = phantomPathParams(entry);
+            if (phantom.length > 0) {
+                undeliverableParams.push(`${opId} (${phantom.join(', ')} on ${path})`);
+            }
             operations.push(entry);
         }
     }
@@ -250,6 +256,13 @@ export const buildCatalog = (params) => {
             'Those fields are marked "x-example-mismatch" and listed by cms_api_describe — ' +
             'copy the example, not the type. Report it against the CMS.');
     }
+    if (undeliverableParams.length > 0) {
+        warnings.push(`${String(undeliverableParams.length)} operation(s) declare a path parameter that their ` +
+            `own path does not contain (${undeliverableParams.slice(0, 5).join(', ')}). ` +
+            'The value has nowhere to go, so this server refuses those calls instead of sending ' +
+            'the request without it. cms_api_describe marks them "notExecutable" and names a ' +
+            'working route where one is known. 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) {

package/dist/api/client.d.ts

@@ -22,6 +22,8 @@ export declare class RequestBuildError extends Error {
 }
 export declare const normalizeBody: (body: unknown) => unknown;
 export declare const unsupportedBodyFormat: (operation: Operation) => string | undefined;
+export declare const phantomPathParams: (operation: Operation) => string[];
+export declare const undeliverablePathParams: (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

@@ -31,7 +31,26 @@ export const unsupportedBodyFormat = (operation) => {
     }
     return `${base} Report it to the human and use another route to that instance.`;
 };
+export const phantomPathParams = (operation) => operation.params
+    .filter((param) => param.location === 'path' && !operation.path.includes(`{${param.name}}`))
+    .map((param) => param.name);
+export const undeliverablePathParams = (operation) => {
+    const phantom = phantomPathParams(operation);
+    if (phantom.length === 0) {
+        return undefined;
+    }
+    return (`Operation ${operation.opId} declares ${phantom.map((name) => `"${name}"`).join(', ')} as a ` +
+        `path parameter, but its path ${operation.path} has no place to put it. The value cannot ` +
+        'reach the API, so the request would go out without it and do something other than what ' +
+        'you asked. The call is not executable through this server — find the operation that ' +
+        'takes the same values where the API really expects them with cms_api_search, and read ' +
+        '"note" in cms_api_describe for a route that has been verified.');
+};
 export const buildUrl = (baseUrl, operation, args) => {
+    const undeliverable = undeliverablePathParams(operation);
+    if (undeliverable !== undefined) {
+        throw new RequestBuildError(undeliverable);
+    }
     let path = operation.path;
     const provided = args.path ?? {};
     for (const param of operation.params) {
@@ -94,11 +113,11 @@ const readBody = async (response) => {
         return text.slice(0, 2000);
     }
 };
-const isLoginPage = (response, body) => {
-    if ((response.headers.get('content-type') ?? '').includes('text/html')) {
-        return true;
-    }
-    return typeof body === 'string' && body.trimStart().startsWith('<');
+const isLoginPage = (body) => typeof body === 'string' && body.trimStart().startsWith('<');
+const describeResponse = (response, body) => {
+    const contentType = response.headers.get('content-type') ?? 'no content type';
+    const text = typeof body === 'string' ? body : JSON.stringify(body ?? null);
+    return `${contentType}, body starts with "${text.trimStart().slice(0, 80).replace(/\s+/g, ' ')}"`;
 };
 const extractMessage = (body, fallback) => {
     if (typeof body === 'string') {
@@ -163,17 +182,18 @@ export class AdminApiClient {
                 response = await attempt(await this.tokens.refresh());
             }
             body = await readBody(response);
-            if (response.ok && isLoginPage(response, body)) {
+            if (response.ok && isLoginPage(body)) {
                 response = await attempt(await this.tokens.refresh());
                 body = await readBody(response);
-                if (response.ok && isLoginPage(response, body)) {
+                if (response.ok && isLoginPage(body)) {
                     return {
                         ok: false,
                         error: {
                             status: response.status,
                             message: `${operation.method.toUpperCase()} ${url} answered ${String(response.status)} with ` +
                                 'the instance login page instead of a result: the admin session is not valid and ' +
-                                're-authenticating did not change that. Nothing was written by this call.',
+                                're-authenticating did not change that. Nothing was written by this call. ' +
+                                `The response was ${describeResponse(response, body)}.`,
                             hint: 'Check the credentials this server runs with, then retry. Treat every write since ' +
                                 'the last verified read as unconfirmed and read those entities back.',
                         },

package/dist/api/operation-notes.js

@@ -57,37 +57,50 @@ export const OPERATION_NOTES = {
             'A body of { limit, offset, langCode } answers 400 complaining about langCode, because ' +
             'the validator is describing the query parameter you did not send.',
     },
+    AdminProductsController_removeMany: {
+        note: 'Not executable through this server: the document declares "ids" as a path parameter ' +
+            'while the path is /products, so the value has nowhere to go and the request would go ' +
+            'out as a bare DELETE /products. The verified way to delete a chosen set is the ' +
+            'operation on DELETE /api/admin/products/category/{pageId} with a body of ' +
+            '{ "ids": [ … ] } — find it with cms_api_search { "query": "products category delete" }. ' +
+            'The same route with the ids in the query string answers 500 instead, so send them in ' +
+            'the body. Deleting products one by one with AdminProductsController_remove is the other ' +
+            'route and needs no category.',
+    },
     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.',
+        note: 'The status id goes in "statusId". The older field name "id" is accepted for the same ' +
+            'value, and a body carrying neither answers 400 rather than writing an empty status. ' +
+            'The call re-indexes what it changed, so the new status is visible to ' +
+            'AdminProductsController_findAll and not only to a read by id. For a single product, ' +
+            'sending statusId through AdminProductsController_update does the same job.',
         verifyWith: {
             opId: 'AdminProductsController_findOne',
             check: 'statusId',
-            why: 'the call answers 201 true whether or not any row changed',
+            why: 'the response says the call was accepted, not which products ended up with the status',
         },
     },
     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. ' +
+        note: 'Inside an attribute, "validators", "localizeInfos", "listTitles" and "additionalFields" ' +
+            'are keyed by locale first: validators.en_US.requiredValidator, not ' +
+            'validators.requiredValidator. A flat map answers 400 here, and the message names the ' +
+            'attribute and the field — only AdminAttributesSetsController_updateSchema still accepts ' +
+            'one silently. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
         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',
+            why: 'the raw set is where a locale key is either present or not, whatever the panel shows',
         },
     },
     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. ' +
-            'Dropping an attribute from the set does not remove the values entities already hold ' +
-            'under its key: they stay on every entity, are invisible in the panel, and a ' +
-            'read-modify-write cycle sends them back, so they outlive the attribute indefinitely. ' +
-            'Strip the removed keys from each entity yourself, in the same run. ' +
+        note: 'Inside an attribute, "validators", "localizeInfos", "listTitles" and "additionalFields" ' +
+            'are keyed by locale first, and a flat map answers 400 here as it does on create. ' +
+            'Dropping an attribute from the set clears the values entities held under its key, but ' +
+            'not by the time the call returns: the cleanup runs behind the write, so for a short ' +
+            'window a read still shows the removed key. Do not build an update from a read taken ' +
+            'immediately after removing an attribute — compare the keys you are about to send against ' +
+            'the current set and drop the ones it no longer defines. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
         verifyWith: {
@@ -97,12 +110,18 @@ export const OPERATION_NOTES = {
         },
     },
     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, and so does the residue rule: an attribute removed ' +
-            'here leaves its values on every entity that had one. ' +
+        note: 'The body is the schema object itself, never wrapped as { "schema": … }. Locale-keyed ' +
+            'rules apply here too, and so does the cleanup rule: an attribute removed here has its ' +
+            'values cleared behind the write, so a read taken straight afterwards can still show the ' +
+            'old key. ' +
             LIST_EXTRAS_NOTE,
         example: LIST_ATTRIBUTE_WITH_EXTRAS,
+        silentNoOp: 'This is the one route that does NOT check locale keying: a flat "validators", ' +
+            '"localizeInfos", "listTitles" or "additionalFields" answers 200 and is stored where no ' +
+            'consumer reads it, so a field you meant to make required is simply not enforced. Create ' +
+            'and update of the set answer 400 for the same body. Wrapping the body as ' +
+            '{ "schema": … } is worse and equally quiet: it answers 200 and replaces the set with a ' +
+            'single attribute called "schema". Read the set back after every schema replace.',
         verifyWith: {
             opId: 'AdminAttributesSetsController_findOne',
             check: 'schema[].validators.<locale>',
@@ -120,13 +139,20 @@ export const OPERATION_NOTES = {
             'and reports no error; the only repair is uploading the file again. That matters because ' +
             'previewLink.default[0] is the inline placeholder a site renders while the full image ' +
             'loads, so an image without it cannot be shown progressively. The stored record carries ' +
-            'no "alt" and no "title": alternative text has to live in a sibling attribute, and the ' +
-            'project has to agree on one naming convention for it before the first upload.',
+            'no "alt" and no "title", but the attribute slot you write it into keeps whatever keys ' +
+            'you add: send "alt" and "title" beside the upload\'s own fields and they come back from ' +
+            'the public read. Use exactly those two names — the admin panel offers the same pair on ' +
+            'an image attribute value and writes them into the same slot, so text set either way ' +
+            'survives an edit made the other way.',
     },
     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.',
+        note: 'A create may carry pagesIds. The ids are checked before anything is written: one that ' +
+            'does not exist answers 404 naming it and no menu is created, so a typo costs nothing to ' +
+            'clean up. What the create does NOT do is nest anything — pagesIds is a flat set wherever ' +
+            'it appears, and the pages arrive as siblings at the top level whatever their relationship ' +
+            'in the page tree. Creating the menu empty and attaching with ' +
+            'AdminMenusController_update is equally valid and the better shape when you are building ' +
+            'the tree level by level.',
     },
     AdminMenusController_update: {
         note: '"pagesIds" is a flat set of page ids and nothing else: nesting is NOT taken from the ' +
@@ -145,46 +171,52 @@ export const OPERATION_NOTES = {
     AdminMenusController_createCustomItem: {
         note: 'A custom item is for anything that is not a page: a product, an external address, a ' +
             'column heading. An empty "value" is rejected, so a heading with no link needs a ' +
-            'placeholder target such as "#". The parent reference is a bare number with no kind ' +
-            'attached, while custom items and page items are numbered separately — so a custom item ' +
-            'and a page item can share an id, and children hung on that number are then returned ' +
-            'under BOTH parents. Before nesting anything, read the menu and check that the included ' +
-            'pages and the custom items share no id; if they do, the only route today is to recreate ' +
-            'the custom item until its id differs.',
+            'placeholder target such as "#". The create body takes localizeInfos and value only: the ' +
+            'item arrives at the top level and is nested afterwards with ' +
+            'AdminMenusController_updateCustomItemPosition. Custom items and page items are numbered ' +
+            'separately, so the same number can name one of each — which is why a parent is addressed ' +
+            'by kind as well as number. Reads return "parentType" beside "parentId", and a public read ' +
+            'also returns "itemType" for the item itself, which is the value its children have to send.',
         verifyWith: {
             opId: 'AdminMenusController_findOne',
-            check: 'the ids of included pages against the ids of customItems',
-            why: 'a shared id duplicates a whole branch, and the write that caused it answers 200',
+            check: 'the parent of the item, its parentType, and where it appears in the tree',
+            why: 'a parent resolved to the other kind puts the item under a plausible wrong branch',
         },
     },
     AdminMenusController_updatePosition: {
-        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
-        note: '"position" is required even when the order does not matter, and it must be an object: ' +
-            'omitting it answers 500 about destructuring, and an empty object is not enough — send ' +
-            '{ leftObjectId: null, rightObjectId: null }. Re-parenting through "newParentId" does ' +
-            'apply; the ordering does not.',
-        silentNoOp: 'Re-parenting lands, but sibling order does not change: the call answers success and ' +
-            'every root item keeps the position it had. Public reads do not take item order from ' +
-            'positions either — page items arrive ordered by page id and custom items after them. ' +
-            'There is no body that produces a chosen order today, so build the menu correct in ' +
-            'composition and nesting, tell the human the order is not reproducible, and report it ' +
-            'rather than trying further bodies.',
+        example: {
+            position: { leftObjectId: null, rightObjectId: null },
+            newParentId: 12,
+            newParentType: 'custom',
+        },
+        note: '"position" is required even when the order does not matter, and it must be an object: a ' +
+            'body without it answers 400 naming the field, and an empty object is not enough — send ' +
+            '{ leftObjectId: null, rightObjectId: null }. Both re-parenting and sibling order apply, ' +
+            'and a public read returns the items in that order. Neighbours are addressed by the id of ' +
+            'the item, not of its position, and page items and custom items are numbered separately: ' +
+            'in a mixed row name each neighbour with "leftObjectType" and "rightObjectType", or a ' +
+            'neighbour of the other kind is not found and the item lands at the edge of the list. ' +
+            '"newParentType" says which kind the new parent is; omit it and the number is looked up ' +
+            'among pages first, which is not necessarily the parent you meant.',
         verifyWith: {
             opId: 'AdminMenusController_findOne',
-            check: 'the parent of the item you moved, and the order of its siblings',
-            why: 'the parent change applies while the order does not, and one response covers both',
+            check: 'the parent of the item you moved, its parentType, and the order of its siblings',
+            why: 'a neighbour or parent resolved to the other kind answers success and moves it elsewhere',
         },
     },
     AdminMenusController_updateCustomItemPosition: {
-        example: { position: { leftObjectId: null, rightObjectId: null }, newParentId: 12 },
+        example: {
+            position: { leftObjectId: null, rightObjectId: null },
+            newParentId: 12,
+            newParentType: 'custom',
+        },
         note: 'Same body as AdminMenusController_updatePosition: "position" is required and must be an ' +
-            'object — { leftObjectId: null, rightObjectId: null } when the order does not matter.',
-        silentNoOp: 'Re-parenting lands; sibling order does not. See AdminMenusController_updatePosition — ' +
-            'public reads order items by page id rather than by the positions stored here.',
+            'object — { leftObjectId: null, rightObjectId: null } when the order does not matter — and ' +
+            'the kind of every neighbour and of the new parent is named alongside its number.',
         verifyWith: {
             opId: 'AdminMenusController_findOne',
-            check: 'the parent of the item you moved, and the order of its siblings',
-            why: 'the parent change applies while the order does not, and one response covers both',
+            check: 'the parent of the item you moved, its parentType, and the order of its siblings',
+            why: 'a neighbour or parent resolved to the other kind answers success and moves it elsewhere',
         },
     },
     AdminFormsController_create: {
@@ -201,7 +233,14 @@ export const OPERATION_NOTES = {
         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 ' +
+            'back unless changing them is the point. An existing binding is matched by its own "id" ' +
+            'and by nothing else: an entry carrying the same formId, moduleId and entityIdentifiers ' +
+            'but no id is created as a NEW binding, the previous one is deleted, and the submissions ' +
+            'counted against it stop being counted — the count route for the form goes to zero. ' +
+            'Worse, a public read of the entity keeps naming the previous binding for as long as its ' +
+            'answer is cached, so a site submitting against it answers 400 "Incorrect formIdentifier ' +
+            'for provided config" after the edit rather than during it. Echo formModuleConfigs[].id ' +
+            'back on every entry you are keeping. This is also the only operation that creates a ' +
             'binding: an entry with formId, moduleId and either isGlobal or entityIdentifiers. ' +
             'The rating behaviour of a review form lives in that same entry and has no operation of ' +
             'its own: isRating, ratingCalculation, maxRatingScale, allowHalfRatings, allowRerating ' +
@@ -225,8 +264,9 @@ export const OPERATION_NOTES = {
         },
         verifyWith: {
             opId: 'AdminFormsController_findOne',
-            check: 'formModuleConfigs',
-            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included',
+            check: 'formModuleConfigs[].id',
+            why: 'an omitted formModuleConfigs is applied as "unbind everything", submissions included, ' +
+                'and a binding sent without its id comes back with a new one, which is the same loss',
         },
     },
     AdminFormDataController_create: {
@@ -241,9 +281,13 @@ export const OPERATION_NOTES = {
             '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. A field of type text takes ' +
-            '[{ "htmlValue": "…" }] — a bare string, a list of strings and [{ "value": … }] are all ' +
-            'rejected. On a rating form the score attribute must be marked isRatingValue, or the ' +
+            'here does not prove a visitor\'s submission would pass. A field of type text takes a ' +
+            'list of ONE object carrying EXACTLY ONE of plainValue, htmlValue or mdValue and no ' +
+            'other key: [{ "plainValue": "…" }]. A bare string, a list of strings, ' +
+            '[{ "value": … }], two of the three keys together and the four-key shape an entity ' +
+            'attribute of type text uses (htmlValue, mdValue, plainValue, params) are each ' +
+            'rejected, the last two with a message that names no field. On a rating form the score ' +
+            'attribute must be marked isRatingValue, or the ' +
             'form is invalid with "Form must have a rating marker". This route also treats one ' +
             'authenticated author as one submission per entity, so it rejects the second review of a ' +
             'product with "You have already rated": a bulk import of visitor reviews cannot go ' +
@@ -257,10 +301,10 @@ export const OPERATION_NOTES = {
     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. One field cannot be echoed back at all: ' +
-            'a listing returns "position" as a lexorank string while this operation expects an object ' +
-            'and answers 400 "position must be either object or array" — drop the field from a ' +
-            'read-modify-write body and reorder with the page position operation instead.',
+            'back unchanged unless you mean to re-parent it. "position" is safe to echo back: a ' +
+            'listing returns it as a lexorank string, and this operation accepts that string and ' +
+            'ignores it, so a read-modify-write body no longer has to be stripped of the field. It ' +
+            'also does not reorder anything — the page position operation is what changes order.',
         verifyWith: {
             opId: 'AdminPagesController_findOne',
             check: 'parentId',
@@ -286,25 +330,24 @@ export const OPERATION_NOTES = {
             'under "mailing", which belongs to the mailing module. Placeholders depend on the module: ' +
             '{{ product.title }} and {{ product.<marker> }} for the catalogue, {{ user.<marker> }} ' +
             'for the recipient. Events support six modules — catalog, forms, orders, users, payments ' +
-            'and discounts. There is no content module among them, so an event on a page or a block ' +
-            'attribute cannot be built this way; see silentNoOp.',
-        silentNoOp: 'A moduleId outside the six supported modules is accepted: the event is created, reads ' +
-            'back complete, and never fires — the panel draws no settings for it and nothing is ever ' +
-            'sent. Nothing in the response distinguishes it from a working event. If the task needs ' +
-            '"notify when this page changes", say that events do not cover it rather than creating ' +
-            'the object and reporting success.',
+            'and discounts. A moduleId outside those six answers 400 and the message names every ' +
+            'module that is accepted; the same check runs on update, so an event cannot be moved onto ' +
+            'an unsupported one either. There is no content module among them, so "notify when this ' +
+            'page changes" is not an events task: say so rather than looking for a body that gets ' +
+            'through. Whether an event that fired actually reached anyone is a separate read — ' +
+            'AdminEventsController_findEmailLogs.',
         verifyWith: {
             opId: 'AdminEventsController_findOne',
             check: 'moduleId and localizeInfos.<locale>.title',
-            why: 'an event on an unsupported module reads back fully populated and still does nothing',
+            why: 'a name sent only as "name" is stored and never displayed, and the create still answers 201',
         },
     },
     AdminEventsController_update: {
         note: 'The event name, the mail subject and the mail body all live in ' +
             'localizeInfos.<locale> as "title", "subject" and "template", with "push" for the push ' +
             'channel. Nothing about the message belongs under "mailing". Supported modules are ' +
-            'catalog, forms, orders, users, payments and discounts; any other moduleId is accepted ' +
-            'and the event never fires.',
+            'catalog, forms, orders, users, payments and discounts; any other moduleId answers 400, ' +
+            'checked against the merged result so a partial update cannot slip past it.',
         example: {
             localizeInfos: {
                 en_US: {
@@ -337,28 +380,29 @@ export const OPERATION_NOTES = {
         },
     },
     AdminDiscountsController_createCoupon: {
-        note: 'A coupon created from a code you supply comes back isReusable: true — one code, valid ' +
-            'for everyone, any number of times. "isReusable" is not accepted in the body, only ' +
-            'reported in the response, so the reuse behaviour follows from WHICH operation created ' +
-            'the coupon. For codes that expire on first use, generate them with ' +
-            'AdminDiscountsController_generateCouponsByMask instead. On a "first order" discount the ' +
-            'difference decides whether one customer gets a discount or everyone does, permanently.',
+        note: '"isReusable" is accepted in the body, and the default when you omit it is TRUE for this ' +
+            'operation — one code, valid for everyone, any number of times. That default is the ' +
+            'opposite of the one AdminDiscountsController_generateCouponsByMask applies, so on a ' +
+            '"first order" discount the field decides whether one customer gets the discount or ' +
+            'everyone does, permanently. State the reuse you mean rather than relying on either ' +
+            'default.',
         verifyWith: {
             opId: 'AdminDiscountsController_findOne',
             check: 'the coupon\'s isReusable',
-            why: 'reuse is not something the create body can set, so the response is the only place it appears',
+            why: 'an omitted field takes a default that differs between the two ways of making a coupon',
         },
     },
     AdminDiscountsController_generateCouponsByMask: {
-        note: 'Coupons generated from a mask come back isReusable: false — each code stops working ' +
-            'after the order that used it. That is the only route to single-use codes: a coupon ' +
-            'created from a supplied string is reusable and cannot be changed through the body.',
+        note: '"isReusable" is accepted in the body here too, and the default when you omit it is ' +
+            'FALSE — each generated code stops working after the order that used it. Send the field ' +
+            'explicitly when the reuse matters; the two coupon operations disagree only in what an ' +
+            'omitted value means.',
     },
     AdminProductsController_update: {
         note: 'Always include "blocks" — send [] when there is nothing to set, because omitting it ' +
             'fails the update. Never include "forms": the schema accepts the field and saving rejects ' +
-            'it. This is also the working route for a product status: send statusId here rather than ' +
-            'through the bulk set-status operation.',
+            'it. A product status can be set here with "statusId", or for many products in one call ' +
+            'with AdminProductsController_setStatusForProducts.',
     },
     AdminBlocksController_update: {
         note: 'Omitting blockPages detaches the block from every page it was on. Read the block first ' +

package/dist/tools/api-discovery.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { unsupportedBodyFormat } from '../api/client.js';
+import { undeliverablePathParams, unsupportedBodyFormat } from '../api/client.js';
 import { errorResult, jsonResult } from './result.js';
 const sampleValue = (schema, example) => {
     if (example !== undefined) {
@@ -110,7 +110,7 @@ export const registerApiDiscovery = (server, deps) => {
                     : 'Operation ids come from cms_api_search — do not construct them by hand.',
             });
         }
-        const formatDenial = unsupportedBodyFormat(operation);
+        const formatDenial = unsupportedBodyFormat(operation) ?? undeliverablePathParams(operation);
         const properties = operation.body?.schema.properties;
         const loose = properties
             ? Object.entries(properties)
@@ -170,7 +170,8 @@ export const registerApiDiscovery = (server, deps) => {
             next: formatDenial
                 ? operation.body?.contentType === 'multipart/form-data'
                     ? 'Do not call this with cms_api_call — upload with cms_upload_file or cms_import_file_from_url.'
-                    : 'Do not call this operation — report it as unavailable through MCP.'
+                    : 'Do not call this operation. Take the route named in "notExecutable" or in ' +
+                        '"note" above, and report it as unavailable through MCP when there is none.'
                 : operation.risk === 'read'
                     ? 'Call it with cms_api_call, copying the "example" above.'
                     : operation.verifyWith

package/knowledge/operating-rules.md

@@ -51,7 +51,7 @@ Ordering is a lexorank **string** on parent-scoped Admin operations and a **numb
 
 ## A read straight after a write can lag
 
-Reading an entity **by id** shows your write immediately; lists and searches may lag by seconds. So re-read by id and **never repeat the write** — that makes a duplicate somebody cleans up by hand. Never swallow a failed read into an empty result either: the next run then recreates everything.
+An **admin** read by id shows your write immediately; admin lists and **every public read**, one entity included, lag by seconds. So re-read after a pause and **never repeat the write** — that makes a duplicate somebody cleans up by hand. Never swallow a failed read into an empty result either: the next run then recreates everything.
 
 ## A 200 means accepted not applied
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oneentry/mcp-platform-server",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "MCP server that lets an AI agent operate the OneEntry Admin API, grounded in the project's own rules",
   "license": "MIT",
   "type": "module",