@wootsup/yt-builder-mcp 1.12.0 → 2.1.0

package/dist/tools/library.js

@@ -1,85 +1,12 @@
-/**
- * Layout Library tools — browse + fetch + insert + save the YOOtheme Pro
- * Library catalog (layouts / element presets), PLUS the Image Sourcing pair
- * (Task D1) that fills layout image slots with real photography. Task 2
- * (Layout Library, Spec #2) + Task 3 (Spec #3) + Task 6 (Spec #6) + Task 7
- * (Spec #7) + Task D1 (Image Sourcing).
- *
- *   yootheme_builder_library_browse
- *      → paginated, taxonomy-filtered catalog rows (tableResult — Wave G.2).
- *   yootheme_builder_library_get
- *      → a SINGLE item's full tree + derived section list (the natural next
- *        call after library_browse — id comes straight off a browse row).
- *   yootheme_builder_library_insert
- *      → compose + persist a browsed/fetched item onto a page/template
- *        through the REAL hardened write chain.
- *   yootheme_builder_library_save_as
- *      → the REVERSE direction: save a page/subtree INTO "My Layouts".
- *   yootheme_builder_library_delete
- *      → the INVERSE of library_save_as: remove ONE saved entry from the
- *        isolated "WootsUp AI Layouts" store (source:"ai" only; the curated
- *        catalog is read-only). ADVANCED, like library_save_as.
- *   yootheme_builder_image_search
- *      → search Unsplash / Pexels (real photography) or YOOtheme Pro Images
- *        (curated decorative/background assets) — forwards to the SAME
- *        `?key=<theme apikey>` proxy auth `library_browse` uses (Task A0-C1,
- *        PHP `ImageSearchService`). Returns candidate rows; `total:0` means
- *        no Library API key configured, mirroring browse's empty-catalog hint.
- *   yootheme_builder_image_import
- *      → sideload ONE chosen photo (typically a `full_url` from
- *        image_search) into the site's own Media Library. Returns
- *        `{imported:true, local_url}` to bind via element_update_settings,
- *        or `{imported:false, reason}` on a caught failure (never a 500).
- *
- * browse/get/image_search are read-only forwards, exactly like the sibling
- * L1 read tools (sources_list / template_summary / pages_list): resolve the
- * site via the pool, GET the plugin REST endpoint, project into a table +
- * strict structuredContent, stamp the result-level `_meta` (site_id/
- * site_url/platform/resolved_via) via withSiteMeta. insert/save_as/
- * image_import are WRITE forwards (withWriteSiteRetry — pre-flights a KNOWN
- * read-only token before any body build, mirroring every other write tool's
- * U2 pattern).
- *
- * ── Tiering (Task 7, deliberate) ─────────────────────────────────────────
- * `library_save_as` is registered as an ADVANCED tool — it is NOT added to
- * `ESSENTIAL_TOOLS` (essentials.ts) and does NOT appear as a first-class
- * `tools/list` entry. `tools/list` sits close to the 28000B token-baseline
- * ceiling (see `tests/perf/token-baseline.test.ts`); a 4th Layout-Library L1
- * tool would risk busting it. `CapturingServer` (gateway/capturing-server.ts)
- * automatically captures ANY registered tool whose name is absent from both
- * `ESSENTIAL_TOOLS` and `DIRECT_TOP_LEVEL_TOOLS` into the L2 advanced
- * registry — reachable via `yootheme_builder_advanced({tool, arguments})` —
- * so simply NOT listing this name in essentials.ts is the entire tiering
- * decision (mirrors how `yootheme_builder_clean_implode_directives` /
- * `yootheme_builder_element_unbind_source` are advanced-only today). The
- * name falls through the gateway's domain taxonomy (domains.ts) to "misc"
- * (no `library` domain exists there) — intentional, NOT a bug (see
- * `domain-order.test.ts`'s own pinned "misc" fallthrough cases): it keeps the
- * gateway's own tools/list-visible description text from growing at all,
- * while `{tool: "yootheme_builder_library_save_as"}` discovery and
- * `{tool, arguments}` execution both remain fully reachable (the gateway
- * dispatches by an exact Map lookup, independent of the domain-grouped
- * DESCRIPTION text — see `gateway/advanced-tool/execute.ts`).
- *
- * @license MIT
- */
 import { z } from 'zod';
 import { RestError } from '../errors.js';
 import { withSiteRetry, withWriteSiteRetry } from './pool-resolve-helper.js';
-import { INCLUDE_META_SCHEMA, SITE_ID_SCHEMA } from './shared-schemas.js';
+import { applyMaxChars, MAX_CHARS } from './sparse-fields.js';
+import { ETAG, INCLUDE_META_SCHEMA, SITE_ID_SCHEMA } from './shared-schemas.js';
 import { creating, defineTool, destructive, errorResult, jsonResult, mutating, readOnly, structuredResult, withSiteMeta, } from './tool-builder.js';
 import { budgetedTableResult } from "./budgeted-table.js";
 import { COMPACT_DEFAULT, RESPONSE_BUDGET } from "./response-budget.js";
-// ─── outputSchema (Wave G.2 §4) ────────────────────────────────────
-/**
- * Fixed section-purpose enum (Task 8, Section Corpus Phase 1) — mirrors the
- * PHP-side `SectionPurposeClassifier` / `SectionIndexEntry` purpose values
- * byte-for-byte (design spec §A, Global Constraints). Only applies when
- * `kind="section"`. Declared here (ahead of `LIBRARY_ITEM_SCHEMA`, which
- * consumes it for the browse row's `purpose` field) rather than further
- * down where the original Task 8 pass left it, since Task 8b (this file)
- * now needs it at both the item-schema AND the browse-filter-schema sites.
- */
+import { CONFIRM_PREVIEW_FIELDS, HOST_PROMPT_PROMISE, requireOnExecutedWrite } from './tool-builder/confirm-preview.js';
 export const SECTION_PURPOSE_VALUES = [
     'hero',
     'features',
@@ -94,39 +21,10 @@ export const SECTION_PURPOSE_VALUES = [
     'logos',
     'content',
 ];
-/**
- * Track 1 Task 7 (WootsUp AI Layouts) — the `source` axis for
- * browse/get/insert: `"catalog"` (the remote YOOtheme Pro Library, the
- * DEFAULT) or `"ai"` (the plugin's OWN isolated "WootsUp AI Layouts" store,
- * saved via library_save_as, no apikey). Mirrors the PHP-side
- * `LibrarySourceRegistry` keys byte-for-byte.
- */
 const LIBRARY_SOURCE_VALUES = ['catalog', 'ai'];
-/**
- * The wire default for the `source` axis. It is NEVER forwarded (a catalog
- * browse/get/insert is byte-identical to the pre-Task-7 request — the PHP
- * controller reads the SAME absent-param default), so only `"ai"` ever
- * appears on the wire. Mirrors `LibrarySourceRegistry::DEFAULT_SOURCE`.
- */
 const DEFAULT_LIBRARY_SOURCE = 'catalog';
-/**
- * Track 1 Task 7 (WootsUp AI Layouts) — the `destination` axis for
- * library_save_as: `"ai"` (save INTO the isolated AI store, the DEFAULT) or
- * `"native"` (the escape hatch — save into YOOtheme's native "My Layouts").
- */
 const SAVE_DESTINATION_VALUES = ['ai', 'native'];
-/**
- * The wire default for the `destination` axis — the AI store. NEVER forwarded
- * (an ai-default save is byte-identical to the pre-Task-7 body; the PHP
- * `MyLayoutsStore` reads the SAME absent-param `ai` default), so only
- * `"native"` ever appears on the wire.
- */
 const DEFAULT_SAVE_DESTINATION = 'ai';
-/**
- * Mirrors `CatalogService::mapItem()` (PHP): every key is always PRESENT
- * (never omitted) but each value may be `null` when the raw catalog item
- * did not carry that taxonomy field — hence `.nullable()`, not `.optional()`.
- */
 const LIBRARY_ITEM_META_SCHEMA = z.object({
     topic: z.string().nullable(),
     type: z.string().nullable(),
@@ -134,23 +32,13 @@ const LIBRARY_ITEM_META_SCHEMA = z.object({
     website: z.string().nullable(),
     image: z.string().nullable(),
 });
-/**
- * Task 8b (Section Corpus Phase 1, PLAN-GAP fix) — a `kind="section"` browse
- * row (`SectionCatalog::mapEntry()`, PHP) carries a DIFFERENT shape than a
- * layout/element row: no `meta` wrapper, TOP-LEVEL `topic`/`type`/`website`,
- * plus `layout_id`/`section_index`/`purpose`/`element_signature`/
- * `visual_effects`/`has_images`/`image_count`/`element_count`. All of these
- * are `.optional()` — additive, never present on a layout/element row — so a
- * strict-outputSchema host still accepts the pre-existing byte-unchanged
- * layout/element shape.
- */
 const LIBRARY_ITEM_SCHEMA = z.object({
     id: z.string(),
     name: z.string(),
-    kind: z.enum(['layout', 'element', 'section']),
-    meta: LIBRARY_ITEM_META_SCHEMA,
-    thumbnail_url: z.string().nullable(),
-    layout_id: z.string().optional(),
+    kind: z.enum(['layout', 'element', 'section']).optional(),
+    meta: LIBRARY_ITEM_META_SCHEMA.optional(),
+    thumbnail_url: z.string().nullable().optional(),
+    library_layout_id: z.string().optional(),
     section_index: z.number().optional(),
     purpose: z.enum(SECTION_PURPOSE_VALUES).optional(),
     element_signature: z.string().optional(),
@@ -160,24 +48,21 @@ const LIBRARY_ITEM_SCHEMA = z.object({
     website: z.string().nullable().optional(),
     has_images: z.boolean().optional(),
     image_count: z.number().optional(),
-    // Close-out finding (f): CONTENT elements only — excludes structural
-    // section/row/column wrappers. Distinct from library_get's
-    // `sections[].element_count` (LIBRARY_SECTION_SCHEMA below), which
-    // counts ALL descendants including structural nodes — the same
-    // section reports a different count from each; do not assume parity.
-    element_count: z
+    content_element_count: z
         .number()
         .optional()
-        .describe('CONTENT elements only (excludes structural section/row/column wrappers). ' +
-        'Distinct from library_get\'s sections[].element_count, which counts ALL descendants.'),
+        .describe('CONTENT elements in this section — the section/row/column wrappers are NOT counted. ' +
+        'library_get\'s sections[].element_count and library_insert\'s element_count count ' +
+        'every node including those wrappers, so the same section reads higher there.'),
 });
 export const LIBRARY_BROWSE_OUTPUT_SCHEMA = z.object({
     items: z.array(LIBRARY_ITEM_SCHEMA),
     total: z.number(),
-    // `CatalogService::browse()` always emits the key; `null` means "last page".
     next_cursor: z.string().nullable(),
+    api_key_configured: z.boolean().optional(),
+    images_note: z.string().optional(),
+    detail_note: z.string().optional(),
 });
-// ─── library_get (Task 3) ───────────────────────────────────────────
 const LIBRARY_SECTION_SCHEMA = z.object({
     index: z.number(),
     name: z.string(),
@@ -186,28 +71,14 @@ const LIBRARY_SECTION_SCHEMA = z.object({
 });
 export const LIBRARY_GET_OUTPUT_SCHEMA = z.object({
     id: z.string(),
-    // Task 8b (Section Corpus Phase 1, PLAN-GAP fix): "section" is a valid
-    // resolved kind — `LibraryController::getSection()` (PHP) always
-    // returns a literal `kind: "section"` for a composite-id fetch.
     kind: z.enum(['layout', 'element', 'section']),
     name: z.string(),
     version: z.string(),
-    // The raw fetched tree (`{type, children, version, images, ...}` for a
-    // layout; a single element node for a preset) — an arbitrary JSON
-    // object, not a fixed shape.
     tree: z.record(z.string(), z.unknown()),
-    // Top-level `tree.children` (layouts only — always `[]` for a preset,
-    // even when its own tree happens to carry `children`).
     sections: z.array(LIBRARY_SECTION_SCHEMA),
     images_manifest_count: z.number(),
+    element_count_note: z.string().optional(),
 });
-// ─── library_insert (Task 6) ─────────────────────────────────────────
-/**
- * Mirrors `LibraryInsertService::insert()`'s `$target` union (PHP) exactly:
- * a fresh page, a splice into an EXISTING template/page (layout/section on
- * the layout root, or a preset on a Column), or a splice into a
- * sublayout/fragment element.
- */
 const LIBRARY_INSERT_TARGET_SCHEMA = z.union([
     z.object({
         new_page: z.object({
@@ -242,33 +113,49 @@ const LIBRARY_INSERT_TARGET_SCHEMA = z.union([
             'or a Column for an element preset (kind:"element").'),
     }),
 ]);
-/**
- * A DOWNGRADED UI-invariant violation (2026-07-12 fix, "trusted
- * library-insert downgrades enum/type violations to warnings"): a pure
- * value-shape mismatch (`invalid_enum_value` / `type_mismatch`) that
- * YOOtheme's OWN factory content carried but the site's installed YOOtheme
- * schema doesn't declare — a version-skew artifact, allowed through rather
- * than hard-rejecting the whole insert. Every OTHER violation class still
- * 422s (`library.ui_invariant_violation`) exactly as before.
- */
 const LIBRARY_INSERT_WARNING_SCHEMA = z.object({
     field: z.string(),
     code: z.string(),
     message: z.string(),
 });
-export const LIBRARY_INSERT_OUTPUT_SCHEMA = z.object({
-    template_id: z.string(),
-    inserted_path: z.string(),
-    element_count: z.number(),
-    images_mode: z.enum(['placeholder', 'curated']),
-    images_resolved: z.object({
+const LIBRARY_INSERT_IMAGE_FAILURE_SCHEMA = z.object({
+    prop_path: z.string(),
+    exception_class: z.string(),
+    message: z.string(),
+});
+export const LIBRARY_INSERT_OUTPUT_SCHEMA = z
+    .object({
+    layout_id: z.string(),
+    inserted_path: z.string().optional(),
+    inserted_paths: z.array(z.string()).optional(),
+    element_count: z.number().optional(),
+    images_mode: z.enum(['placeholder', 'curated', 'as_saved']).optional(),
+    images_resolved: z
+        .object({
         downloaded: z.number(),
         placeholders: z.number(),
-    }),
-    new_etag: z.string(),
-    frontend_url: z.string().nullable(),
+    })
+        .optional(),
+    etag: z.string().optional(),
+    new_etag: z.string().optional(),
+    frontend_url: z.string().nullable().optional(),
+    images_note: z.string().optional(),
+    media_note: z.string().optional(),
     warnings: z.array(LIBRARY_INSERT_WARNING_SCHEMA).optional(),
-});
+    image_import_failures: z.array(LIBRARY_INSERT_IMAGE_FAILURE_SCHEMA).optional(),
+    root_type_inserted: z.string().optional(),
+    would_remove_count: z.number().optional(),
+    would_remove_types: z.array(z.string()).optional(),
+    ...CONFIRM_PREVIEW_FIELDS,
+})
+    .superRefine((v, ctx) => requireOnExecutedWrite(v, ctx, [
+    'inserted_path',
+    'element_count',
+    'images_mode',
+    'images_resolved',
+    'new_etag',
+    'frontend_url',
+]));
 const LIBRARY_TABLE_COLUMNS = [
     { key: 'id', label: 'ID', width: 10, llmOnly: true },
     { key: 'name', label: 'NAME', width: 26 },
@@ -283,17 +170,6 @@ function asNullableString(v) {
 function isSectionPurpose(v) {
     return typeof v === 'string' && SECTION_PURPOSE_VALUES.includes(v);
 }
-/**
- * Task 8b (Section Corpus Phase 1, PLAN-GAP fix) — `requestedKind` is the
- * caller's own `library_browse({kind})` argument. It is needed because a
- * `kind="section"` row from `SectionCatalog::mapEntry()` (PHP) carries NO
- * per-row `kind` field at all (unlike layout/element rows, which always do)
- * — the whole response is homogeneous per browse call, since `kind` is a
- * REST-level filter. So: `r.kind` wins when the row DOES carry one
- * (layout/element, and defensively "section" too, should REST ever add it);
- * otherwise fall back to what the caller asked for; otherwise "layout"
- * (today's pre-Task-8b default, byte-unchanged).
- */
 function mapLibraryItem(raw, requestedKind) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
@@ -313,15 +189,11 @@ function mapLibraryItem(raw, requestedKind) {
         },
         thumbnail_url: asNullableString(r.thumbnail_url),
     };
-    // ADDITIVE ONLY: a layout/element row returns exactly `base` — no
-    // section keys are ever added, not even as `undefined` — so the
-    // pre-Task-8b shape stays byte-unchanged (regression-tested via
-    // toStrictEqual in library.test.ts).
     if (kind !== 'section')
         return base;
     return {
         ...base,
-        layout_id: typeof r.layout_id === 'string' ? r.layout_id : undefined,
+        library_layout_id: typeof r.library_layout_id === 'string' ? r.library_layout_id : undefined,
         section_index: typeof r.section_index === 'number' ? r.section_index : undefined,
         purpose: isSectionPurpose(r.purpose) ? r.purpose : undefined,
         element_signature: typeof r.element_signature === 'string' ? r.element_signature : undefined,
@@ -333,41 +205,17 @@ function mapLibraryItem(raw, requestedKind) {
         website: asNullableString(r.website),
         has_images: typeof r.has_images === 'boolean' ? r.has_images : undefined,
         image_count: typeof r.image_count === 'number' ? r.image_count : undefined,
-        element_count: typeof r.element_count === 'number' ? r.element_count : undefined,
+        content_element_count: typeof r.content_element_count === 'number' ? r.content_element_count : undefined,
     };
 }
-/**
- * PAGES_LIBRARY_MEDIA-10 — the Layout Library + Image Sourcing domain is
- * WordPress-only (the `src/modules/library` host module bootstraps on WP only;
- * plugin 1.10.0). On a Joomla site the REST endpoints do not exist, so a
- * library/image call used to return an empty `{items:[],total:0}` (or a bare
- * 404) with no hint about WHY. This returns an explicit
- * `not_supported_on_platform` (501) instead, so the agent stops retrying and
- * knows the capability simply is not there on this platform. Returns `null` on
- * WordPress so the real forward runs.
- */
-function joomlaNotSupportedGuard(client, toolName, context) {
-    if (client.getPlatform().kind !== 'joomla')
-        return null;
-    return errorResult({
-        error: new Error(`${toolName} is not supported on Joomla — the Library + image domain is ` +
-            'WordPress-only in plugin 1.10.0.'),
-        context: { ...context, platform: 'joomla', error_code: 'not_supported_on_platform', status: 501 },
-        hint: 'This capability exists only on WordPress sites. On Joomla, build layouts with ' +
-            'the element/page tools; there is no Library catalog or image proxy to browse.',
-    });
-}
+export const BROWSE_IMAGES_NOTE = 'Images: an insert uses generic PLACEHOLDERS by default '
+    + '- has_images describes the catalog entry, not the inserted page. Pass '
+    + 'images:"curated" to yootheme_builder_library_insert to download the real photos.';
 export async function handleLibraryBrowse({ client }, { kind, source, topic, type, role, website, element_type, purpose, has_effects, query, limit, cursor, include_meta }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_library_browse', { kind: kind ?? 'layout' });
-    if (guard !== null)
-        return guard;
     try {
         const qs = new URLSearchParams();
         if (kind !== undefined)
             qs.set('kind', kind);
-        // Only forward a NON-default source (the PHP controller reads the same
-        // absent-param `catalog` default) so a catalog browse is byte-identical
-        // to the pre-Task-7 request.
         if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
             qs.set('source', source);
         if (typeof topic === 'string' && topic !== '')
@@ -398,26 +246,51 @@ export async function handleLibraryBrowse({ client }, { kind, source, topic, typ
             .filter((i) => i !== undefined);
         const total = typeof data.total === 'number' ? data.total : items.length;
         const nextCursor = typeof data.next_cursor === 'string' ? data.next_cursor : null;
+        const apiKeyConfigured = typeof data.api_key_configured === 'boolean' ? data.api_key_configured : undefined;
+        const detailNote = typeof data.detail_note === 'string' && data.detail_note !== '' ? data.detail_note : undefined;
         const rows = items;
         const toolkitResult = budgetedTableResult(rows, {
             columns: [...LIBRARY_TABLE_COLUMNS],
             header: (count) => `${String(count)} of ${String(total)} library items`,
-            footer: 'Activate one on a page with yootheme_builder_element_add / page_dynamize, ' +
-                'or pass `cursor` (next_cursor) for the next page.',
+            footer: 'Activate one on a page with yootheme_builder_element_add / page_generate_dynamic, ' +
+                'or pass `cursor` (next_cursor) for the next page. ' +
+                BROWSE_IMAGES_NOTE,
             includeMeta: include_meta,
         }, RESPONSE_BUDGET.BULKY);
-        // HARD CONSTRAINT (Task 8): browse NEVER returns an image content
-        // block, even for kind="section" rows that carry a thumbnail_url —
-        // tableResult() only ever emits text rows. Use
-        // yootheme_builder_library_get's include_thumbnail on a shortlisted
-        // id for an actual image.
         return structuredResult(toolkitResult, {
             items,
             total,
             next_cursor: nextCursor,
+            images_note: BROWSE_IMAGES_NOTE,
+            ...(apiKeyConfigured !== undefined ? { api_key_configured: apiKeyConfigured } : {}),
+            ...(detailNote !== undefined ? { detail_note: detailNote } : {}),
         });
     }
     catch (e) {
+        if (isLibraryNotConfigured(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    error_code: LIBRARY_NOT_CONFIGURED,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: LIBRARY_NOT_CONFIGURED_HINT,
+            });
+        }
+        if (isLibraryUpstreamUnavailable(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    error_code: LIBRARY_UPSTREAM_UNAVAILABLE,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: LIBRARY_UPSTREAM_UNAVAILABLE_HINT,
+            });
+        }
         return errorResult({
             error: e,
             context: { kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE, topic, type, role, website, element_type, purpose, has_effects, query },
@@ -425,6 +298,69 @@ export async function handleLibraryBrowse({ client }, { kind, source, topic, typ
         });
     }
 }
+const LIBRARY_UPSTREAM_UNAVAILABLE = 'library_upstream_unavailable';
+export const LIBRARY_UPSTREAM_UNAVAILABLE_HINT = 'This is a CATALOG FETCH FAILURE, not an empty catalog. Do NOT retry with different '
+    + 'filters or a different id; the YOOtheme Pro Library never answered with data. An HTTP 401 '
+    + 'here means api.yootheme.com REFUSED the Library API key this site has configured. WHY it '
+    + 'was refused is not visible from here, so do NOT name a cause: report that the key was '
+    + 'refused and let the site owner check it with YOOtheme. The keyless source:"ai" store and '
+    + 'yootheme_builder_page_get_layout still work.';
+function restErrorBody(e) {
+    if (!(e instanceof RestError))
+        return undefined;
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    return body;
+}
+const LIBRARY_NOT_CONFIGURED = 'library_api_key_not_configured';
+export const LIBRARY_NOT_CONFIGURED_HINT = 'This is a CONFIGURATION GAP, not an empty catalog and not a refusal: no request reached the '
+    + 'upstream catalog, so nothing here tells you what it holds. Do NOT retry with different '
+    + 'filters, and do NOT assume the customer forgot to enter a key. Run yootheme_builder_diagnose '
+    + 'and read library_key.state first: it separates "no key entered", which the customer fixes in '
+    + 'the YOOtheme Customizer theme settings, from a lookup that found no YOOtheme update site at '
+    + 'all, where there is nothing to fix in the key field. Its hint names who has to act. Without a '
+    + 'key you can still BROWSE the bundled section index (library_browse with kind:"section", '
+    + 'including its filters), read the keyless source:"ai" store, and use '
+    + 'yootheme_builder_page_get_layout. What the key unlocks is kind:"layout"/"element" browsing '
+    + 'plus library_get detail and library_insert for every kind.';
+function isLibraryUpstreamUnavailable(e) {
+    return libraryCodeMatches(e, LIBRARY_UPSTREAM_UNAVAILABLE);
+}
+function isLibraryNotConfigured(e) {
+    return libraryCodeMatches(e, LIBRARY_NOT_CONFIGURED);
+}
+function libraryCodeMatches(e, code) {
+    if (e instanceof RestError && typeof e.code === 'string' && e.code.endsWith(code)) {
+        return true;
+    }
+    const body = restErrorBody(e);
+    if (body === undefined)
+        return false;
+    if (body.error_code === code)
+        return true;
+    const data = body.data;
+    return (data !== null
+        && typeof data === 'object'
+        && !Array.isArray(data)
+        && data.error_code === code);
+}
+function libraryUnavailableContext(e) {
+    const body = restErrorBody(e);
+    if (body === undefined)
+        return {};
+    const data = body.data !== null && typeof body.data === 'object' && !Array.isArray(body.data)
+        ? body.data
+        : {};
+    const out = {};
+    const upstream = body.upstream_status ?? data.upstream_status;
+    if (typeof upstream === 'number')
+        out.upstream_status = upstream;
+    const configured = body.api_key_configured ?? data.api_key_configured;
+    if (typeof configured === 'boolean')
+        out.api_key_configured = configured;
+    return out;
+}
 function mapLibrarySection(raw) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
@@ -437,14 +373,6 @@ function mapLibrarySection(raw) {
     }
     return { index: r.index, name: r.name, path: r.path, element_count: r.element_count };
 }
-/**
- * Task 8 (Section Corpus Phase 1) — the REST `/library/get` response's
- * `thumbnail` field (present ONLY when `include_thumbnail=true` was passed
- * AND the server-side fetch succeeded — see `LibraryController::attachThumbnail()`).
- * A missing/malformed field (either key absent, or either value not a
- * non-empty string) is treated as "no thumbnail" — the caller never emits a
- * broken image block.
- */
 function mapThumbnail(raw) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
@@ -455,15 +383,76 @@ function mapThumbnail(raw) {
         return undefined;
     return { mime_type: r.mime_type, data_base64: r.data_base64 };
 }
-export async function handleLibraryGet({ client }, { id, kind, source, include_thumbnail }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_library_get', { id });
-    if (guard !== null)
-        return guard;
+function asPlainRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : {};
+}
+function collectElementTypeCounts(node, counts) {
+    const n = asPlainRecord(node);
+    if (typeof n.type === 'string' && n.type !== '') {
+        counts.set(n.type, (counts.get(n.type) ?? 0) + 1);
+    }
+    if (Array.isArray(n.children)) {
+        for (const child of n.children)
+            collectElementTypeCounts(child, counts);
+    }
+}
+function elementTypeCounts(tree) {
+    const counts = new Map();
+    collectElementTypeCounts(tree, counts);
+    return Object.fromEntries([...counts.entries()].sort((a, b) => b[1] - a[1] || a[0].localeCompare(b[0])));
+}
+function encodedLength(payload) {
+    return JSON.stringify(payload).length;
+}
+function truncatedHint(sectionCount) {
+    const sectionAdvice = sectionCount > 0
+        ? ' To inspect ONE section instead of the whole item, call this tool again with ' +
+            'kind:"section" and an id of "<this id>#<sectionIndex>" (see sections[].index) — a ' +
+            'single section is a fraction of the full size.'
+        : '';
+    const whatSurvived = sectionCount > 0
+        ? ' What is missing is the ELEMENTS inside the sections; the `sections` list beside ' +
+            'this note is complete and unabridged (every section, its name and element count).'
+        : '';
+    return ('The full tree was replaced by this summary because the payload was too large.' +
+        whatSurvived +
+        ' To INSERT this item you do not need the tree at all — call ' +
+        'yootheme_builder_library_insert with the same id directly.' +
+        sectionAdvice +
+        ' Passing a larger max_chars recovers more of the tree.');
+}
+const LIBRARY_GET_DEFAULT_STRUCTURED_BUDGET_CHARS = 20_000;
+function shrinkLibraryGetTree(payload, budget) {
+    const bytesFull = encodedLength(payload);
+    const tree = asPlainRecord(payload.tree);
+    if (bytesFull <= budget)
+        return tree;
+    const rootType = typeof tree.type === 'string' ? tree.type : undefined;
+    const sections = Array.isArray(payload.sections) ? payload.sections : [];
+    const counts = elementTypeCounts(tree);
+    const summaryTree = {
+        ...(rootType !== undefined ? { type: rootType } : {}),
+        truncated: true,
+        bytes_full: bytesFull,
+        element_type_counts: counts,
+        hint: truncatedHint(sections.length),
+    };
+    if (encodedLength({ ...payload, tree: summaryTree }) <= budget)
+        return summaryTree;
+    const top = Object.fromEntries(Object.entries(counts).slice(0, 5));
+    return {
+        ...summaryTree,
+        element_type_counts: top,
+        element_type_counts_truncated: Object.keys(counts).length > Object.keys(top).length,
+    };
+}
+export async function handleLibraryGet({ client }, { id, kind, source, include_thumbnail, max_chars }) {
     try {
         const qs = new URLSearchParams({ id });
         if (kind !== undefined)
             qs.set('kind', kind);
-        // Only forward a NON-default source (see handleLibraryBrowse).
         if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
             qs.set('source', source);
         if (include_thumbnail === true)
@@ -486,24 +475,58 @@ export async function handleLibraryGet({ client }, { id, kind, source, include_t
             sections,
             images_manifest_count: typeof data.images_manifest_count === 'number' ? data.images_manifest_count : 0,
         };
-        // Task 8: an image content block is ADDITIONAL to the JSON text
-        // block, never a replacement — `structuredContent` (below) stays
-        // exactly the pre-Task-8 shape so a strict-outputSchema host never
-        // sees an undeclared key, and a large base64 blob is never
-        // duplicated into structuredContent alongside the image block.
-        // Gated on the CALLER's own `include_thumbnail === true` (not just
-        // "the REST body happened to carry a thumbnail field") — a defensive
-        // belt-and-braces on top of the server-side opt-in gate, so a future
-        // REST regression can never surprise-inject an unrequested,
-        // token-costly image block.
+        const structuredBudget = max_chars ?? LIBRARY_GET_DEFAULT_STRUCTURED_BUDGET_CHARS;
+        const finalTree = shrinkLibraryGetTree(payload, structuredBudget);
+        const structuredPayload = {
+            id: payload.id,
+            kind: payload.kind,
+            name: payload.name,
+            version: payload.version,
+            tree: finalTree,
+            sections: payload.sections,
+            images_manifest_count: payload.images_manifest_count,
+        };
         const thumbnail = include_thumbnail === true ? mapThumbnail(data.thumbnail) : undefined;
-        const jsonEnvelope = jsonResult(payload);
+        const jsonEnvelope = jsonResult(structuredPayload);
         const content = thumbnail !== undefined
             ? [...jsonEnvelope.content, { type: 'image', data: thumbnail.data_base64, mimeType: thumbnail.mime_type }]
             : jsonEnvelope.content;
-        return structuredResult({ content }, payload);
+        return structuredResult(applyMaxChars({ content }, max_chars), structuredPayload);
     }
     catch (e) {
+        if (isLibraryNotConfigured(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    id,
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    error_code: LIBRARY_NOT_CONFIGURED,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: LIBRARY_NOT_CONFIGURED_HINT,
+            });
+        }
+        if (isLibraryUpstreamUnavailable(e)) {
+            const usedDefaultSource = source === undefined || source === DEFAULT_LIBRARY_SOURCE;
+            return errorResult({
+                error: e,
+                context: {
+                    id,
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    error_code: LIBRARY_UPSTREAM_UNAVAILABLE,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: usedDefaultSource
+                    ? LIBRARY_UPSTREAM_UNAVAILABLE_HINT
+                        + ' If this id came from your OWN store (library_save_as, or '
+                        + 'library_browse with source:"ai"), it does not live in the remote '
+                        + 'catalog at all: retry with source:"ai". The catalog was queried '
+                        + 'because `source` defaults to "catalog".'
+                    : LIBRARY_UPSTREAM_UNAVAILABLE_HINT,
+            });
+        }
         return errorResult({
             error: e,
             context: { id, kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE },
@@ -512,15 +535,6 @@ export async function handleLibraryGet({ client }, { id, kind, source, include_t
         });
     }
 }
-/**
- * 2026-07-12 fix ("trusted library-insert downgrades enum/type violations to
- * warnings") — maps the REST `warnings[]` array (each `{field, code,
- * message}`) if present. Mirrors the OTHER `map*` helpers in this file:
- * malformed entries are dropped rather than propagated, and an absent/empty
- * source array maps to `undefined` (the key is OMITTED from the result, not
- * emitted as `[]`) — this is the "if present" contract: pre-fix inserts
- * (a REST body carrying no `warnings` key at all) round-trip byte-unchanged.
- */
 function mapLibraryInsertWarnings(raw) {
     if (!Array.isArray(raw) || raw.length === 0)
         return undefined;
@@ -535,55 +549,148 @@ function mapLibraryInsertWarnings(raw) {
     }
     return warnings.length > 0 ? warnings : undefined;
 }
+function mapLibraryInsertImageFailures(raw) {
+    if (!Array.isArray(raw) || raw.length === 0)
+        return undefined;
+    const failures = [];
+    for (const entry of raw) {
+        if (entry === null || typeof entry !== 'object')
+            continue;
+        const f = entry;
+        if (typeof f.prop_path !== 'string' || typeof f.exception_class !== 'string')
+            continue;
+        if (typeof f.message !== 'string')
+            continue;
+        failures.push({
+            prop_path: f.prop_path,
+            exception_class: f.exception_class,
+            message: f.message,
+        });
+    }
+    return failures.length > 0 ? failures : undefined;
+}
+function isLibraryInsertPreview(raw) {
+    return raw !== null && typeof raw === 'object' && raw.preview === true;
+}
+function mapLibraryInsertPreview(r) {
+    const types = Array.isArray(r.would_remove_types)
+        ? r.would_remove_types.filter((t) => typeof t === 'string')
+        : undefined;
+    return {
+        preview: true,
+        applied: false,
+        requires_confirmation: true,
+        requires_confirm: true,
+        operation: typeof r.operation === 'string' ? r.operation : 'insert this Library item',
+        warning: typeof r.warning === 'string' ? r.warning : '',
+        instruction: typeof r.instruction === 'string'
+            ? r.instruction
+            : 'Ask the user to confirm, then call again with `confirm: true`.',
+        hint: typeof r.hint === 'string' ? r.hint : '',
+        received_confirm: r.received_confirm,
+        received_confirm_type: typeof r.received_confirm_type === 'string' ? r.received_confirm_type : 'absent',
+        expected_confirm: typeof r.expected_confirm === 'string' ? r.expected_confirm : '',
+        ...(typeof r.step_reversible === 'boolean' ? { step_reversible: r.step_reversible } : {}),
+        layout_id: typeof r.layout_id === 'string' ? r.layout_id : '',
+        ...(typeof r.etag === 'string' && r.etag !== '' ? { etag: r.etag } : {}),
+        ...(typeof r.would_remove_count === 'number' ? { would_remove_count: r.would_remove_count } : {}),
+        ...(types !== undefined ? { would_remove_types: types } : {}),
+    };
+}
 function mapLibraryInsertResult(raw) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
     const r = raw;
-    if (typeof r.template_id !== 'string' || typeof r.inserted_path !== 'string')
+    if (typeof r.layout_id !== 'string' || typeof r.inserted_path !== 'string')
         return undefined;
     const resolvedRaw = r.images_resolved !== null && typeof r.images_resolved === 'object'
         ? r.images_resolved
         : {};
     const warnings = mapLibraryInsertWarnings(r.warnings);
+    const imageFailures = mapLibraryInsertImageFailures(r.image_import_failures);
+    const mode = r.images_mode === 'curated' || r.images_mode === 'as_saved' ? r.images_mode : 'placeholder';
+    const placeholders = typeof resolvedRaw.placeholders === 'number' ? resolvedRaw.placeholders : 0;
+    const imagesNote = mode === 'placeholder' && placeholders > 0
+        ? `${String(placeholders)} image(s) are generic placeholders, not the photos shown on `
+            + 'the catalog thumbnail. The layout renders, but it does not look like its preview. '
+            + 'Re-insert with images:"curated" to download the real images into the Media Library.'
+        : undefined;
     return {
-        template_id: r.template_id,
+        layout_id: r.layout_id,
         inserted_path: r.inserted_path,
         element_count: typeof r.element_count === 'number' ? r.element_count : 0,
-        images_mode: r.images_mode === 'curated' ? 'curated' : 'placeholder',
+        images_mode: mode,
         images_resolved: {
             downloaded: typeof resolvedRaw.downloaded === 'number' ? resolvedRaw.downloaded : 0,
-            placeholders: typeof resolvedRaw.placeholders === 'number' ? resolvedRaw.placeholders : 0,
+            placeholders,
         },
         new_etag: typeof r.new_etag === 'string' ? r.new_etag : '',
         frontend_url: typeof r.frontend_url === 'string' ? r.frontend_url : null,
+        ...(imagesNote !== undefined ? { images_note: imagesNote } : {}),
+        ...(typeof r.media_note === 'string' && r.media_note !== '' ? { media_note: r.media_note } : {}),
         ...(warnings !== undefined ? { warnings } : {}),
+        ...(imageFailures !== undefined ? { image_import_failures: imageFailures } : {}),
+        root_type_inserted: typeof r.root_type_inserted === 'string' ? r.root_type_inserted : '',
     };
 }
-export async function handleLibraryInsert({ client }, { id, kind, source, target, section_index, images, etag }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_library_insert', { id });
-    if (guard !== null)
-        return guard;
+export async function handleLibraryInsert({ client }, { id, kind, source, target, section_index, images, insert_mode, index, confirm, etag }) {
     const resolvedImages = images ?? 'placeholder';
     try {
         const body = { id, target, images: resolvedImages };
         if (kind !== undefined)
             body.kind = kind;
-        // Only forward a NON-default source (see handleLibraryBrowse); the PHP
-        // LibraryInsertService reads the same absent-param `catalog` default.
         if (source !== undefined && source !== DEFAULT_LIBRARY_SOURCE)
             body.source = source;
         if (section_index !== undefined)
             body.section_index = section_index;
+        if (insert_mode !== undefined)
+            body.insert_mode = insert_mode;
+        if (index !== undefined)
+            body.index = index;
+        if (confirm !== undefined)
+            body.confirm = confirm;
         if (typeof etag === 'string' && etag !== '')
             body.etag = etag;
         const data = await client.post('/library/insert', { body });
+        if (isLibraryInsertPreview(data)) {
+            const preview = mapLibraryInsertPreview(data);
+            return structuredResult(jsonResult(preview), preview);
+        }
         const mapped = mapLibraryInsertResult(data);
         if (mapped === undefined) {
-            throw new Error('Malformed /library/insert response — missing template_id/inserted_path.');
+            throw new Error('Malformed /library/insert response — missing layout_id/inserted_path.');
         }
         return structuredResult(jsonResult(mapped), mapped);
     }
     catch (e) {
+        if (isLibraryNotConfigured(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    id,
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    images: resolvedImages,
+                    error_code: LIBRARY_NOT_CONFIGURED,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: LIBRARY_NOT_CONFIGURED_HINT,
+            });
+        }
+        if (isLibraryUpstreamUnavailable(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    id,
+                    kind: kind ?? 'layout',
+                    source: source ?? DEFAULT_LIBRARY_SOURCE,
+                    images: resolvedImages,
+                    error_code: LIBRARY_UPSTREAM_UNAVAILABLE,
+                    ...libraryUnavailableContext(e),
+                },
+                hint: LIBRARY_UPSTREAM_UNAVAILABLE_HINT,
+            });
+        }
         return errorResult({
             error: e,
             context: { id, kind: kind ?? 'layout', source: source ?? DEFAULT_LIBRARY_SOURCE, images: resolvedImages },
@@ -591,26 +698,20 @@ export async function handleLibraryInsert({ client }, { id, kind, source, target
         });
     }
 }
-/**
- * PAGES_LIBRARY_MEDIA-4 — status/code-aware catch hint for `library_insert`.
- *
- * The former static hint always said "Verify the id via library_get first" —
- * but a 404 `not_found`/`unavailable` means the catalog item cannot be FETCHED
- * (no Library API key configured, or the id is genuinely absent), so library_get
- * returns an empty success and confirms nothing → a loop. On that class steer
- * to the real fixes (configure the apikey, or use the keyless source:"ai")
- * instead. Keep the target-column / stale-etag guidance for the 422/412 classes
- * they actually describe.
- */
 function libraryInsertHint(e) {
     if (e instanceof RestError) {
         const code = e.code ?? '';
-        if (e.status === 404 || code.includes('not_found') || code.includes('unavailable')) {
-            return ('The Library item could not be fetched (missing key or absent id). Do NOT ' +
-                'loop on yootheme_builder_library_get — it returns an empty success for an ' +
-                'unfetchable id. Either configure the YOOtheme Pro Library API key ' +
-                '(Customizer → Theme Settings → apikey), or use source:"ai" (your keyless ' +
-                '"WootsUp AI Layouts" store).');
+        if (isLibraryNotConfigured(e)) {
+            return LIBRARY_NOT_CONFIGURED_HINT;
+        }
+        if (isLibraryUpstreamUnavailable(e)) {
+            return LIBRARY_UPSTREAM_UNAVAILABLE_HINT;
+        }
+        if (e.status === 404 || code.includes('not_found')) {
+            return ('The Library item could not be fetched (no key configured, or the id is not in ' +
+                'the catalog). Do NOT loop on yootheme_builder_library_get. Either configure the ' +
+                'YOOtheme Pro Library API key (Customizer, Theme Settings, apikey), or use ' +
+                'source:"ai" (your keyless "WootsUp AI Layouts" store).');
         }
         if (e.status === 422) {
             return ('A 422 target_not_a_column means a preset (kind:"element") was pointed at a ' +
@@ -626,7 +727,6 @@ function libraryInsertHint(e) {
         'hull first with yootheme_builder_scaffold_section. A 412 means the etag is stale — ' +
         're-read (get_etag/pages_list) and retry.');
 }
-// ─── library_save_as (Task 7) ────────────────────────────────────────────
 const LIBRARY_SAVE_SOURCE_SCHEMA = z.object({
     template_id: z
         .string()
@@ -642,6 +742,9 @@ export const LIBRARY_SAVE_AS_OUTPUT_SCHEMA = z.object({
     name: z.string(),
     storage: z.string(),
     invalid_source_possible: z.boolean(),
+    destination: z.string().optional(),
+    kind: z.string().optional(),
+    storage_note: z.string().optional(),
 });
 function mapLibrarySaveAsResult(raw) {
     if (raw === null || typeof raw !== 'object')
@@ -650,25 +753,31 @@ function mapLibrarySaveAsResult(raw) {
     if (typeof r.library_id !== 'string' || typeof r.name !== 'string' || typeof r.storage !== 'string') {
         return undefined;
     }
+    const storage = r.storage;
+    const isOwnStore = storage === 'ai' || storage === 'wootsup-ai-layouts';
     return {
         library_id: r.library_id,
         name: r.name,
-        storage: r.storage,
+        storage,
         invalid_source_possible: r.invalid_source_possible === true,
+        storage_note: isOwnStore
+            ? 'Saved to your isolated "WootsUp AI Layouts" store, NOT to YOOtheme\'s '
+                + 'built-in My Layouts: it will not appear in the builder\'s Library panel. '
+                + 'Reuse it with library_browse/library_insert using source:"ai", remove it '
+                + 'with library_delete. Saving again with destination:"native" puts a copy '
+                + 'where the builder shows it, but that copy is one-way: no tool here can '
+                + 'find or delete it afterwards.'
+            : 'Saved to YOOtheme\'s built-in My Layouts, so the builder shows it under '
+                + 'that panel. This copy is ONE-WAY for this server: library_browse/'
+                + 'library_get/library_insert reach only "catalog" and "ai" entries, and '
+                + 'library_delete removes only "ai" ones, so nothing here can find, reuse '
+                + 'or remove it again. Save it with destination:"ai" as well if you want to '
+                + 'keep working with it from here.',
     };
 }
 export async function handleLibrarySaveAs({ client }, { source, name, destination }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_library_save_as', {
-        template_id: source.template_id,
-    });
-    if (guard !== null)
-        return guard;
     try {
         const body = { source, name };
-        // Only forward a NON-default destination (the PHP MyLayoutsStore reads
-        // the same absent-param `ai` default), so an ai-default save is
-        // byte-identical to the pre-Task-7 body — only the `native` escape
-        // hatch ever appears on the wire.
         if (destination !== undefined && destination !== DEFAULT_SAVE_DESTINATION)
             body.destination = destination;
         const data = await client.post('/library/save', { body });
@@ -688,12 +797,22 @@ export async function handleLibrarySaveAs({ client }, { source, name, destinatio
         });
     }
 }
-// ─── library_delete (PAGES_LIBRARY_MEDIA-16) ─────────────────────────────
-export const LIBRARY_DELETE_OUTPUT_SCHEMA = z.object({
+export const LIBRARY_DELETE_OUTPUT_SCHEMA = z
+    .object({
     deleted: z.boolean(),
     id: z.string(),
     deleted_count: z.number(),
     source: z.string(),
+    ...CONFIRM_PREVIEW_FIELDS,
+})
+    .superRefine((v, ctx) => {
+    if (v.requires_confirmation === true && v.deleted !== false) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['deleted'],
+            message: 'a confirm preview must report deleted:false — nothing was removed',
+        });
+    }
 });
 function mapLibraryDeleteResult(raw) {
     if (raw === null || typeof raw !== 'object')
@@ -709,14 +828,8 @@ function mapLibraryDeleteResult(raw) {
     };
 }
 export async function handleLibraryDelete({ client }, { id, source }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_library_delete', { id });
-    if (guard !== null)
-        return guard;
     try {
-        const body = { id };
-        // Only forward a NON-default source. The PHP controller reads the same
-        // absent-param "ai" default; the curated catalog (source:"catalog") is
-        // read-only, so forwarding it is what makes the controller answer 403.
+        const body = { id, confirm: true };
         if (source !== undefined && source !== 'ai')
             body.source = source;
         const data = await client.post('/library/delete', { body });
@@ -734,11 +847,6 @@ export async function handleLibraryDelete({ client }, { id, source }) {
         });
     }
 }
-/**
- * Status/code-aware catch hint for library_delete. A 404 means the id was
- * already gone (not a failure to act on — the end state is what you wanted); a
- * 403 means a read-only source (only source:"ai" is deletable).
- */
 function libraryDeleteHint(e) {
     if (e instanceof RestError) {
         if (e.status === 404) {
@@ -753,57 +861,57 @@ function libraryDeleteHint(e) {
     return ('Pass the `id` of an entry from yootheme_builder_library_browse({source:"ai"}). Only ' +
         'source:"ai" entries are deletable — the curated library is read-only.');
 }
-// ─── image_search / image_import (Task D1, Image Sourcing) ────────────────
-//
-// Thin GET/POST forwards to `/library/image-search` (Task C1) mirroring
-// library_browse's read-projection pattern, and `/library/image-import`
-// mirroring library_insert's write-forward pattern. Response shapes are
-// pinned by the PHP controller tests
-// (tests/php/unit/Library/LibraryControllerImageSearchTest.php +
-// LibraryControllerImageImportTest.php):
-//   GET  /library/image-search  → {items, total, source, query, hint?}
-//   POST /library/image-import  → {imported:true, local_url} |
-//                                  {imported:false, reason}
-const IMAGE_SOURCE_VALUES = ['unsplash', 'pexels', 'proimages'];
-/**
- * Cross-source orientation dialect (D1 concern, see the plan doc): the
- * Unsplash proxy accepts "squarish", the Pexels proxy accepts "square" for
- * the SAME concept. `ImageSearchService::buildQueryString()` (PHP) forwards
- * whatever string is supplied verbatim, per-source, with NO translation — so
- * this schema accepts BOTH spellings instead of forcing one source's
- * vocabulary onto the other (which would either reject a legitimate Pexels
- * "square" request or silently mis-filter it).
- */
+const IMAGE_SOURCE_VALUES = ['unsplash', 'pexels', 'proimages', 'local'];
 const IMAGE_ORIENTATION_VALUES = ['landscape', 'portrait', 'squarish', 'square'];
+const IMAGE_LICENSE_KEYS = {
+    license: z.string().nullable().optional(),
+    attribution_required: z.boolean().nullable().optional(),
+    license_url: z.string().optional(),
+    license_note: z.string().optional(),
+};
 const IMAGE_RESULT_SCHEMA = z.object({
     id: z.string(),
     source: z.string(),
     thumb_url: z.string(),
     full_url: z.string(),
-    width: z.number(),
-    height: z.number(),
-    alt: z.string(),
-    author: z.string(),
-    author_url: z.string(),
-    orientation: z.string(),
+    width: z.number().nullable(),
+    height: z.number().nullable(),
+    alt: z.string().optional(),
+    author: z.string().optional(),
+    author_url: z.string().optional(),
+    orientation: z.string().optional(),
+    ...IMAGE_LICENSE_KEYS,
 });
 export const IMAGE_SEARCH_OUTPUT_SCHEMA = z.object({
     items: z.array(IMAGE_RESULT_SCHEMA),
     total: z.number(),
     source: z.string(),
     query: z.string(),
-    // Present ONLY on the empty-result path (no Library API key configured,
-    // or genuinely zero matches — the REST layer cannot and must not
-    // distinguish the two; see LibraryControllerImageSearchTest).
     hint: z.string().optional(),
+    api_key_configured: z.boolean().optional(),
+    next_offset: z.number().int().min(0).optional(),
+    local_note: z.string().optional(),
 });
 export const IMAGE_IMPORT_OUTPUT_SCHEMA = z.object({
     imported: z.boolean(),
-    // Present only when imported:true.
     local_url: z.string().optional(),
-    // Present only when imported:false (a caught importer failure — never a 500).
     reason: z.string().optional(),
+    failure: z.enum(['rejected', 'unavailable']).optional(),
+    media_note: z.string().optional(),
+    ...IMAGE_LICENSE_KEYS,
 });
+function pickImageLicense(r) {
+    return {
+        ...(typeof r.license === 'string' || r.license === null ? { license: r.license } : {}),
+        ...(typeof r.attribution_required === 'boolean' || r.attribution_required === null
+            ? { attribution_required: r.attribution_required }
+            : {}),
+        ...(typeof r.license_url === 'string' ? { license_url: r.license_url } : {}),
+        ...(typeof r.license_note === 'string' && r.license_note !== ''
+            ? { license_note: r.license_note }
+            : {}),
+    };
+}
 function mapImageResult(raw) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
@@ -815,12 +923,13 @@ function mapImageResult(raw) {
         source: typeof r.source === 'string' ? r.source : '',
         thumb_url: typeof r.thumb_url === 'string' ? r.thumb_url : '',
         full_url: typeof r.full_url === 'string' ? r.full_url : '',
-        width: typeof r.width === 'number' ? r.width : 0,
-        height: typeof r.height === 'number' ? r.height : 0,
-        alt: typeof r.alt === 'string' ? r.alt : '',
-        author: typeof r.author === 'string' ? r.author : '',
-        author_url: typeof r.author_url === 'string' ? r.author_url : '',
-        orientation: typeof r.orientation === 'string' ? r.orientation : '',
+        width: typeof r.width === 'number' ? r.width : null,
+        height: typeof r.height === 'number' ? r.height : null,
+        ...(typeof r.alt === 'string' ? { alt: r.alt } : {}),
+        ...(typeof r.author === 'string' ? { author: r.author } : {}),
+        ...(typeof r.author_url === 'string' ? { author_url: r.author_url } : {}),
+        ...(typeof r.orientation === 'string' ? { orientation: r.orientation } : {}),
+        ...pickImageLicense(r),
     };
 }
 const IMAGE_TABLE_COLUMNS = [
@@ -828,42 +937,44 @@ const IMAGE_TABLE_COLUMNS = [
     { key: 'dimensions', label: 'SIZE', width: 10 },
     { key: 'author', label: 'AUTHOR', width: 18 },
     { key: 'orientation', label: 'ORIENT', width: 10 },
-    // llmOnly: the copyable next-call value (yootheme_builder_image_import's
-    // `url` arg) — excluded from the Rich Card UI (too long for a table
-    // cell) but present in the ASCII text the LLM reads. Always present in
-    // structuredContent.items[].full_url regardless of table membership.
     { key: 'full_url', label: 'FULL_URL', width: 50, llmOnly: true },
 ];
-export async function handleImageSearch({ client }, { source, query, per_page, orientation, color, include_meta }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_image_search', { query });
-    if (guard !== null)
-        return guard;
+export async function handleImageSearch({ client }, { source, query, per_page, orientation, color, offset, include_meta }) {
     const resolvedSource = source ?? 'unsplash';
     try {
         const qs = new URLSearchParams();
         qs.set('source', resolvedSource);
-        qs.set('query', query);
+        if (typeof query === 'string' && query !== '')
+            qs.set('query', query);
         if (per_page !== undefined)
             qs.set('per_page', String(per_page));
         if (typeof orientation === 'string' && orientation !== '')
             qs.set('orientation', orientation);
         if (typeof color === 'string' && color !== '')
             qs.set('color', color);
+        if (offset !== undefined)
+            qs.set('offset', String(offset));
         const data = await client.get(`/library/image-search?${qs.toString()}`);
         const rawItems = Array.isArray(data.items) ? data.items : [];
         const items = rawItems.map(mapImageResult).filter((i) => i !== undefined);
         const total = typeof data.total === 'number' ? data.total : items.length;
         const resolvedResponseSource = typeof data.source === 'string' ? data.source : resolvedSource;
-        const resolvedQuery = typeof data.query === 'string' ? data.query : query;
+        const resolvedQuery = typeof data.query === 'string' ? data.query : (query ?? '');
         const hint = typeof data.hint === 'string' ? data.hint : undefined;
+        const nextOffset = typeof data.next_offset === 'number' && Number.isInteger(data.next_offset) && data.next_offset >= 0
+            ? data.next_offset
+            : undefined;
+        const localNote = typeof data.local_note === 'string' && data.local_note !== '' ? data.local_note : undefined;
+        const apiKeyConfigured = typeof data.api_key_configured === 'boolean' ? data.api_key_configured : undefined;
         const rows = items.map((i) => ({
             ...i,
-            dimensions: `${String(i.width)}x${String(i.height)}`,
+            dimensions: `${i.width === null ? '?' : String(i.width)}x${i.height === null ? '?' : String(i.height)}`,
         }));
         const toolkitResult = budgetedTableResult(rows, {
             columns: [...IMAGE_TABLE_COLUMNS],
             header: (count) => `${String(count)} of ${String(total)} ${resolvedResponseSource} image${total === 1 ? '' : 's'} for "${resolvedQuery}"`,
             footer: hint
+                ?? localNote
                 ?? 'Import a chosen row\'s full_url with yootheme_builder_image_import, then bind '
                     + 'the returned local_url via element_update_settings.',
             includeMeta: include_meta,
@@ -874,18 +985,108 @@ export async function handleImageSearch({ client }, { source, query, per_page, o
             source: resolvedResponseSource,
             query: resolvedQuery,
             ...(hint !== undefined ? { hint } : {}),
+            ...(nextOffset !== undefined ? { next_offset: nextOffset } : {}),
+            ...(localNote !== undefined ? { local_note: localNote } : {}),
+            ...(apiKeyConfigured !== undefined ? { api_key_configured: apiKeyConfigured } : {}),
         });
     }
     catch (e) {
+        if (isImageSearchNotConfigured(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    source: resolvedSource,
+                    query,
+                    error_code: IMAGE_SEARCH_NOT_CONFIGURED,
+                    ...imageSearchUnavailableContext(e),
+                },
+                hint: IMAGE_SEARCH_NOT_CONFIGURED_HINT,
+            });
+        }
+        if (isImageSearchUnavailable(e)) {
+            return errorResult({
+                error: e,
+                context: {
+                    source: resolvedSource,
+                    query,
+                    error_code: 'image_search_unavailable',
+                    ...imageSearchUnavailableContext(e),
+                },
+                hint: IMAGE_SEARCH_UNAVAILABLE_HINT,
+            });
+        }
         return errorResult({
             error: e,
             context: { source: resolvedSource, query, per_page, orientation, color },
-            hint: 'total:0 usually means no YOOtheme Pro Library API key is configured (the same '
-                + 'theme apikey library_browse/insert use). Run yootheme_builder_diagnose to verify auth. '
+            hint: 'Run yootheme_builder_diagnose to verify auth and connectivity, then retry. '
                 + 'yootheme_builder_image_import still works with a direct image URL (no key needed).',
         });
     }
 }
+const IMAGE_SEARCH_UNAVAILABLE = 'image_search_unavailable';
+export const IMAGE_SEARCH_UNAVAILABLE_HINT = 'This is a SEARCH FAILURE, not an empty result. Do NOT retry with a broader query; the '
+    + 'provider never answered with results. An HTTP 401 here means the YOOtheme Pro Library API '
+    + 'key this site has configured was REFUSED for this call. WHY it was refused is not visible '
+    + 'from here, so do NOT name a cause: report that the key was refused and let the site owner '
+    + 'check it with YOOtheme. yootheme_builder_image_import still works with a direct Unsplash, '
+    + 'Pexels or YOOtheme library image URL (no key needed).';
+const IMAGE_SEARCH_NOT_CONFIGURED = 'image_search_api_key_not_configured';
+export const IMAGE_SEARCH_NOT_CONFIGURED_HINT = 'This is a CONFIGURATION GAP, not an empty result: no YOOtheme Pro Library API key could be '
+    + 'read on this site, so no search request was made and nothing is known about what the '
+    + 'provider holds. Do NOT retry with a broader query. Run yootheme_builder_diagnose and read '
+    + 'library_key.state before naming a fix: it separates "no key entered", which the customer '
+    + 'fixes in the YOOtheme Customizer theme settings, from a lookup that found no YOOtheme update '
+    + 'site at all, where there is nothing to fix in the key field. yootheme_builder_image_import '
+    + 'still works with a direct Unsplash, Pexels or YOOtheme library image URL (no key needed).';
+function imageSearchErrorBody(e) {
+    if (!(e instanceof RestError))
+        return undefined;
+    const body = e.body;
+    if (body === null || typeof body !== 'object' || Array.isArray(body))
+        return undefined;
+    return body;
+}
+function isImageSearchUnavailable(e) {
+    return imageSearchCodeMatches(e, IMAGE_SEARCH_UNAVAILABLE);
+}
+function isImageSearchNotConfigured(e) {
+    return imageSearchCodeMatches(e, IMAGE_SEARCH_NOT_CONFIGURED);
+}
+function imageSearchCodeMatches(e, code) {
+    if (e instanceof RestError && typeof e.code === 'string' && e.code.endsWith(code)) {
+        return true;
+    }
+    const body = imageSearchErrorBody(e);
+    if (body === undefined)
+        return false;
+    if (body.error_code === code)
+        return true;
+    const data = body.data;
+    return (data !== null
+        && typeof data === 'object'
+        && !Array.isArray(data)
+        && data.error_code === code);
+}
+function imageSearchUnavailableContext(e) {
+    const body = imageSearchErrorBody(e);
+    if (body === undefined)
+        return {};
+    const data = body.data !== null && typeof body.data === 'object' && !Array.isArray(body.data)
+        ? body.data
+        : {};
+    const out = {};
+    const upstream = body.upstream_status ?? data.upstream_status;
+    if (typeof upstream === 'number')
+        out.upstream_status = upstream;
+    const configured = body.api_key_configured ?? data.api_key_configured;
+    if (typeof configured === 'boolean')
+        out.api_key_configured = configured;
+    return out;
+}
+const IMAGE_IMPORT_FAILURE_VALUES = ['rejected', 'unavailable'];
+function mapImageImportFailure(raw) {
+    return IMAGE_IMPORT_FAILURE_VALUES.find((v) => v === raw);
+}
 function mapImageImportResult(raw) {
     if (raw === null || typeof raw !== 'object')
         return undefined;
@@ -895,17 +1096,41 @@ function mapImageImportResult(raw) {
     if (r.imported) {
         if (typeof r.local_url !== 'string' || r.local_url === '')
             return undefined;
-        return { imported: true, local_url: r.local_url };
+        return {
+            imported: true,
+            local_url: r.local_url,
+            ...(typeof r.media_note === 'string' && r.media_note !== '' ? { media_note: r.media_note } : {}),
+            ...pickImageLicense(r),
+        };
     }
+    const failure = mapImageImportFailure(r.failure);
     return {
         imported: false,
         reason: typeof r.reason === 'string' && r.reason !== '' ? r.reason : 'Import failed for an unknown reason.',
+        ...(failure === undefined ? {} : { failure }),
     };
 }
-export async function handleImageImport({ client }, { url }) {
-    const guard = joomlaNotSupportedGuard(client, 'yootheme_builder_image_import', { url });
-    if (guard !== null)
-        return guard;
+export async function handleImageImport({ client }, args) {
+    if (args.url !== undefined
+        && args.full_url !== undefined
+        && args.url !== args.full_url) {
+        return errorResult({
+            error: new Error('The "url" and "full_url" arguments are two names for ONE value and were '
+                + 'given different ones. Pass only the url to import.'),
+            context: { url: args.url, full_url: args.full_url },
+            hint: 'Drop one of the two. "full_url" is accepted only because that is the name a '
+                + 'yootheme_builder_image_search row carries.',
+        });
+    }
+    const url = args.url ?? args.full_url;
+    if (url === undefined || url === '') {
+        return errorResult({
+            error: new Error('The "url" argument is required — a full_url from yootheme_builder_image_search '
+                + 'is accepted under either name.'),
+            context: {},
+            hint: 'Pass a full_url from yootheme_builder_image_search.',
+        });
+    }
     try {
         const data = await client.post('/library/image-import', { body: { url } });
         const mapped = mapImageImportResult(data);
@@ -915,16 +1140,6 @@ export async function handleImageImport({ client }, { url }) {
         return structuredResult(jsonResult(mapped), mapped);
     }
     catch (e) {
-        // T3 (2026-07-25, Sheet-0 handover) — the REST route returns the graceful
-        // { imported:false, reason } envelope for SSRF-disallowed-host /
-        // invalid-url / authz-denied rejections but with a 4xx STATUS, so the
-        // client raises a RestError and the raw HTTP error would otherwise hide
-        // the reason (the "image_import just 400s with no explanation" report).
-        // When the error body IS that graceful envelope, surface it as a normal
-        // { imported:false, reason } result — identical to the 200-status
-        // graceful paths above — so the agent sees WHY (e.g. "host not on the
-        // image-import allowlist") and can recover with an allowlisted full_url
-        // from yootheme_builder_image_search.
         if (e instanceof RestError) {
             const mapped = mapImageImportResult(e.body);
             if (mapped !== undefined && !mapped.imported) {
@@ -936,7 +1151,7 @@ export async function handleImageImport({ client }, { url }) {
             context: { url },
             hint: 'Verify the url is a reachable http(s) image URL (typically a full_url from '
                 + 'yootheme_builder_image_search). A read_only_token error means this bearer key '
-                + 'needs the write scope — regenerate it in YT Builder MCP → Keys.',
+                + 'needs the write scope — regenerate it in MCP for YOOtheme Pro → Bearer Keys.',
         });
     }
 }
@@ -945,12 +1160,15 @@ export function buildLibraryTools(pool) {
         defineTool({
             name: 'yootheme_builder_library_browse',
             description: 'Browse the YOOtheme Pro Library catalog: pre-designed page LAYOUTS, element ' +
-                'PRESETS, or purpose-classified SECTIONS (hero/features/cta/...). Filter with ' +
-                '`kind` ("layout" default | "element" | "section"), `topic`, `type`/`role`, ' +
-                '`element_type`, `purpose`/`has_effects` (sections only), `website`, `query`. ' +
-                'Returns `{items, total, next_cursor}`; a "section" id is the composite ' +
-                '"<layoutId>#<sectionIndex>" — feeds straight into library_get/library_insert. ' +
-                '`total:0` usually means no Library API key configured.',
+                'PRESETS, or purpose-classified SECTIONS. Filter: `kind`, `topic`, `type`/`role`, ' +
+                '`element_type`, `purpose`, `query`. A section id is the composite ' +
+                '"<layoutId>#<sectionIndex>" — feeds library_get/insert. ' +
+                '`source`: "catalog" (default) or "ai" — YOUR saved entries from ' +
+                'library_save_as, which library_delete removes again — both gateway-only, ' +
+                'call via yootheme_builder_advanced({tool, arguments}). `total:0` = the ' +
+                'catalog matched nothing; a read with no data answers ' +
+                '`library_upstream_unavailable` or `library_api_key_not_configured`, never an ' +
+                'empty page.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 kind: z
@@ -985,7 +1203,13 @@ export function buildLibraryTools(pool) {
                     .string()
                     .min(1)
                     .optional()
-                    .describe('Page-role filter (e.g. "Home", "Contact", "Services"). Only applies when kind="layout". Exact match.'),
+                    .describe('Filters on how the SOURCE demo website filed this layout in ITS OWN menu ' +
+                    '(e.g. "Home", "Contact", "Services") — sourced verbatim from the YOOtheme ' +
+                    'Pro Library catalog, NOT a classification of what the layout actually ' +
+                    'builds. A layout can carry a role unrelated to its content if that is ' +
+                    'where the source site\'s own navigation put it; prefer `query` (name ' +
+                    'match) or browsing without this filter when the exact wording is ' +
+                    'unknown. Only applies when kind="layout". Exact match.'),
                 website: z
                     .string()
                     .min(1)
@@ -999,7 +1223,11 @@ export function buildLibraryTools(pool) {
                 purpose: z
                     .enum(SECTION_PURPOSE_VALUES)
                     .optional()
-                    .describe('Section-purpose filter (e.g. "hero", "features", "cta"). Only applies when kind="section". Exact match.'),
+                    .describe('Section-purpose filter (e.g. "hero", "features", "cta"). Only applies when ' +
+                    'kind="section". Exact match. BROAD buckets, not topics: hundreds of sections ' +
+                    'share one, none names a specific subject, so the closest-looking value is a ' +
+                    'guess. For a subject ("services") use `query` instead - it matches the ' +
+                    'section NAME.'),
                 has_effects: z
                     .boolean()
                     .optional()
@@ -1029,13 +1257,12 @@ export function buildLibraryTools(pool) {
         }),
         defineTool({
             name: 'yootheme_builder_library_get',
-            description: 'Fetch a SINGLE YOOtheme Pro Library layout or element preset by `id` — call ' +
-                'after yootheme_builder_library_browse (items[].id feeds this). Returns ' +
-                '`{id, kind, name, version, tree, sections, images_manifest_count}`: `tree` is ' +
-                'the raw JSON; `sections` lists `tree.children` (layouts only, presets return ' +
-                '`[]`), each `{index, name, path, element_count}`. `include_thumbnail:true` ' +
-                'also returns an image block (costs tokens — see its own description). ' +
-                'Read-only; does not insert/bind.',
+            description: 'Fetch ONE Library layout or element preset by `id` — call after ' +
+                'library_browse (items[].id feeds this). `include_thumbnail:true` adds an ' +
+                'image (costs tokens). This DETAIL endpoint checks the key, browse does not: no ' +
+                'key gives 503 library_api_key_not_configured, a refused key 503 ' +
+                'library_upstream_unavailable. Report the refusal, not a cause. `source`: ' +
+                '"catalog" (default) or "ai" for your own library_save_as (gateway-only) entries.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 id: z
@@ -1054,6 +1281,15 @@ export function buildLibraryTools(pool) {
                     .describe('Which library the `id` belongs to: "catalog" (remote YOOtheme Pro Library, ' +
                     'default) or "ai" (your OWN "WootsUp AI Layouts"). Must match the source the ' +
                     'id came from in yootheme_builder_library_browse.'),
+                max_chars: MAX_CHARS.describe('Cap (chars) on this result. On THIS tool it ALSO bounds structuredContent — ' +
+                    'an oversized `tree` is replaced by a compact summary inside the same key ' +
+                    '(element_type_counts, truncated:true, bytes_full, hint) instead of riding ' +
+                    'through whole; small items are unaffected. Applies even when omitted ' +
+                    '(default safety cap: 20000 chars). Over the plugin-served endpoint both ' +
+                    'legs already carry the same shortened payload. ' +
+                    'Raising it stops helping at the limit your own client puts on a single tool ' +
+                    'result, which this server cannot see. ' +
+                    'Out of range, the cap that actually applied comes back as `max_chars`.'),
                 include_thumbnail: z
                     .boolean()
                     .default(false)
@@ -1069,13 +1305,14 @@ export function buildLibraryTools(pool) {
         }),
         defineTool({
             name: 'yootheme_builder_library_insert',
-            description: 'Insert a YOOtheme Pro Library item (layout, section, or preset) onto a page — ' +
-                'call after yootheme_builder_library_get/browse. `target`: new_page (creates a ' +
-                'page), {template_id,element_path?} (splices onto the layout root, or a preset ' +
-                'onto a Column), or sublayout (splices rows into a fragment). A preset ' +
-                '(kind:"element") MUST target a Column — 422 otherwise; scaffold one first with ' +
-                'yootheme_builder_scaffold_section. `images`: "placeholder" (default) or ' +
-                '"curated" (downloads to Media Library). Optional `etag` locks (412 if stale).',
+            description: 'Insert a Library item onto a page — call after library_get/browse. `target`: ' +
+                'new_page, {template_id,element_path?} (splices onto the layout root, or a ' +
+                'preset onto a Column), or sublayout. A preset (kind:"element") MUST target a ' +
+                'Column (422 otherwise) — scaffold one with scaffold_section. `images`: ' +
+                '"placeholder" (default) or "curated" (downloads to Media Library). Placement: ' +
+                '`insert_mode` for layouts, `index` for presets. `etag` ' +
+                'locks (412 if stale). `source`: "catalog" (default) or "ai" to insert your own ' +
+                'saved entry.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 id: z
@@ -1105,29 +1342,42 @@ export function buildLibraryTools(pool) {
                     .enum(['placeholder', 'curated'])
                     .default('placeholder')
                     .describe('"placeholder" (default, safe, no network I/O) or "curated" (downloads + sideloads every unique image into the Media Library).'),
-                etag: z
-                    .string()
+                insert_mode: z
+                    .enum(['replace', 'top', 'bottom'])
+                    .default('replace')
+                    .describe('How the composed content joins the target\'s EXISTING children — mirrors the ' +
+                    'Library dialog\'s own picker. "replace" (default) drops them; "top"/"bottom" ' +
+                    'prepend/append. Ignored for target:new_page (a fresh page starts empty). ' +
+                    'REFUSED for kind:"element" — a preset takes `index`.'),
+                index: z
+                    .number()
+                    .int()
+                    .min(0)
                     .optional()
-                    .describe('Optional optimistic-lock ETag (from get_etag/pages_list). Mismatched → 412; caller must re-read and retry.'),
+                    .describe('kind:"element" ONLY (refused otherwise): where the preset lands among the ' +
+                    'Column\'s children. 0 = first, omit to append, past-end clamps — as in ' +
+                    'element_add. A preset never replaces what the Column holds.'),
+                confirm: z
+                    .boolean()
+                    .optional()
+                    .describe('Set true to proceed when insert_mode:"replace" would remove the target\'s ' +
+                    'existing content. Omit for a preview naming what would be lost; "top"/' +
+                    '"bottom", an empty target and kind:"element" (a preset only ever adds) ' +
+                    'never need it. ' +
+                    HOST_PROMPT_PROMISE),
+                etag: ETAG,
             },
             outputSchema: LIBRARY_INSERT_OUTPUT_SCHEMA,
-            annotations: creating('Insert Layout Library Item'),
+            annotations: destructive('Insert Layout Library Item'),
             handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_library_insert', async (client, site) => withSiteMeta(await handleLibraryInsert({ client }, rest), site)),
         }),
-        // Task 7 (Layout Library, Spec #7) — ADVANCED tool (deliberately NOT
-        // added to essentials.ts/ESSENTIAL_TOOLS): reachable ONLY via
-        // yootheme_builder_advanced({tool, arguments}), never a first-class
-        // tools/list entry. See the module docblock's "Tiering" note.
         defineTool({
             name: 'yootheme_builder_library_save_as',
             description: 'Save a page or subtree into a reusable library — the REVERSE of ' +
-                'yootheme_builder_library_insert. `source`: {template_id, ' +
-                'element_path?} (omit element_path to save the WHOLE page). ' +
-                '`destination`: "ai" (default — your isolated "WootsUp AI Layouts", ' +
-                'reusable via library_browse/insert source:"ai") or "native" ' +
-                '(YOOtheme\'s built-in My Layouts). Returns `{library_id, name, ' +
-                'storage, invalid_source_possible}` (the last flags bound sources ' +
-                'that may need re-binding after reload). Advanced/gateway-only.',
+                'library_insert. `source`: {template_id, element_path?} (omit element_path to ' +
+                'save the WHOLE page). `destination`: "ai" (default — your isolated "WootsUp AI ' +
+                'Layouts", reusable via library_browse source:"ai") or "native" (YOOtheme\'s ' +
+                'built-in My Layouts).',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 source: LIBRARY_SAVE_SOURCE_SCHEMA.describe('The page/subtree to save.'),
@@ -1135,10 +1385,6 @@ export function buildLibraryTools(pool) {
                     .string()
                     .min(1)
                     .describe('Display name for the new library entry (e.g. "Hero Section").'),
-                // PAGES_LIBRARY_MEDIA-15: `.optional()` (not `.default('ai')`) so
-                // the generated schema does NOT advertise a REQUIRED field that
-                // also carries a default. The handler applies the `ai` default
-                // when omitted (it only forwards a NON-default `native`).
                 destination: z
                     .enum(SAVE_DESTINATION_VALUES)
                     .optional()
@@ -1148,31 +1394,15 @@ export function buildLibraryTools(pool) {
                     '(the escape hatch: save into YOOtheme\'s built-in "My Layouts").'),
             },
             outputSchema: LIBRARY_SAVE_AS_OUTPUT_SCHEMA,
-            // PAGES_LIBRARY_MEDIA-15: title names the DEFAULT destination (the AI
-            // Layouts store), not "My Layouts" (which is the non-default `native`).
             annotations: creating('Save to AI Layouts library'),
             handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_library_save_as', async (client, site) => withSiteMeta(await handleLibrarySaveAs({ client }, rest), site)),
         }),
-        // PAGES_LIBRARY_MEDIA-16 — ADVANCED tool (deliberately NOT added to
-        // essentials.ts/ESSENTIAL_TOOLS): reachable ONLY via
-        // yootheme_builder_advanced({tool, arguments}). The INVERSE of
-        // library_save_as. Annotated destructive() — it IRREVERSIBLY removes a
-        // saved AI-Layouts entry (a layout the user deliberately saved via
-        // library_save_as; there is no undo). This matches the codebase's own
-        // "irreversible → destructive → host confirm-gate" precedent:
-        // element_delete + pages_delete are destructive (audit F9), and
-        // clean_implode_directives was re-classified mutating→destructive in
-        // Wave H5 for the same reason (cannot be restored). Deleting saved user
-        // data should fire the host's destructive-approval gate, not slip
-        // through as an ordinary mutating write.
         defineTool({
             name: 'yootheme_builder_library_delete',
-            description: 'Delete ONE saved entry from your "WootsUp AI Layouts" store (the isolated library ' +
-                'yootheme_builder_library_save_as writes into) — clean up experimental sections/layouts ' +
-                'the agent saved. Pass the `id` from a library_browse(source:"ai") row. `source` defaults ' +
-                'to "ai", the ONLY deletable store; the curated library is read-only, so source:"catalog" ' +
-                'returns a 403. IRREVERSIBLE — requires confirm:true. Returns `{deleted, id, deleted_count, ' +
-                'source}`; an unknown id returns a 404. Advanced/gateway-only.',
+            description: 'Delete ONE saved entry from your "WootsUp AI Layouts" store (library_save_as ' +
+                'writes into it) — pass the `id` from a library_browse(source:"ai") row. ' +
+                '`source` defaults to "ai", the ONLY deletable store; the curated library is ' +
+                'read-only, source:"catalog" returns 403. IRREVERSIBLE — requires confirm:true.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 id: z
@@ -1186,9 +1416,6 @@ export function buildLibraryTools(pool) {
                     .describe('Which library to delete from. Only "ai" (your OWN "WootsUp AI Layouts") is ' +
                     'deletable; "catalog" (the curated remote YOOtheme Pro Library) is read-only ' +
                     'and returns a 403. Omit to default to "ai".'),
-                // Destructive-tool confirm gate (matches element_delete / pages_delete):
-                // z.literal(true) makes the MCP boundary REJECT any call without
-                // confirm:true, so an irreversible delete can never fire by accident.
                 confirm: z
                     .literal(true)
                     .describe('Required — must be `true`. Deleting a saved AI-Layouts entry is IRREVERSIBLE ' +
@@ -1198,27 +1425,33 @@ export function buildLibraryTools(pool) {
             annotations: destructive('Delete AI Layouts entry'),
             handler: async ({ site_id, ...rest }) => withWriteSiteRetry(pool, site_id, 'yootheme_builder_library_delete', async (client, site) => withSiteMeta(await handleLibraryDelete({ client }, rest), site)),
         }),
-        // Task D1 (Image Sourcing) — read-only forward, mirrors library_browse.
         defineTool({
             name: 'yootheme_builder_image_search',
-            description: 'Search real on-topic photos (Unsplash/Pexels) or YOOtheme Pro Images to fill '
-                + 'layout image slots with REAL, on-brand photography instead of bare '
-                + 'placeholders. Returns candidate rows with `full_url` (pass straight to '
-                + 'yootheme_builder_image_import) plus dimensions/author/orientation. '
-                + '`total:0` usually means no Library API key is configured (the same theme '
-                + 'apikey library_browse/insert use).',
+            description: 'Search on-topic photos (Unsplash/Pexels), YOOtheme Pro Images, or (source:"local") '
+                + 'this site\'s own media library. Rows carry `full_url` (feeds image_import) plus '
+                + 'dimensions/author. `total:0` is the ONLY shape meaning the provider matched '
+                + 'nothing; a search that never happened answers an `error_code` instead. No '
+                + 'apikey gives `image_search_api_key_not_configured`; a provider that REFUSES '
+                + 'gives `error_code: image_search_unavailable`, which no broader query can fix. '
+                + 'A key can be CONFIGURED and still be REFUSED (401): report that the upstream '
+                + 'refused it, never why (source:"local" is exempt — see its field description). '
+                + 'Works on WordPress and Joomla.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 source: z
                     .enum(IMAGE_SOURCE_VALUES)
                     .default('unsplash')
                     .describe('Image source. unsplash/pexels = real photography; proimages = YOOtheme '
-                    + 'Pro curated decorative/background assets, not topical photography.'),
+                    + 'Pro curated decorative/background assets, not topical photography; '
+                    + 'local = this site\'s own media library — no key, no image_import '
+                    + '(bind full_url directly), paginated via `offset`/`next_offset`.'),
                 query: z
                     .string()
                     .min(1)
+                    .optional()
                     .describe('Search terms, e.g. "coffee roasting", "modern architecture interior". '
-                    + 'Search deliberately by industry + tone, not a generic term like "business".'),
+                    + 'Search deliberately by industry + tone, not a generic term like "business". '
+                    + 'Optional only for source:"local" (lists without one); the other three require it.'),
                 per_page: z
                     .number()
                     .int()
@@ -1229,40 +1462,59 @@ export function buildLibraryTools(pool) {
                 orientation: z
                     .enum(IMAGE_ORIENTATION_VALUES)
                     .optional()
-                    .describe('landscape for heroes/banners, portrait for cards. "squarish" is the '
-                    + 'Unsplash spelling, "square" is the Pexels spelling for the same shape. '
-                    + 'Both are accepted; ignored for proimages.'),
+                    .describe('landscape for heroes/banners, portrait for cards. Each square spelling '
+                    + 'belongs to ONE source: "squarish" to unsplash, "square" to pexels. '
+                    + 'Crossing them fails two different ways, and only one is visible: '
+                    + '"square" on unsplash is refused upstream (HTTP 400, '
+                    + 'image_search_unavailable), while "squarish" on pexels is silently '
+                    + 'ignored and you get unfiltered rows back. Even on its own source '
+                    + '"squarish" is approximate: unsplash still returns landscape and '
+                    + 'portrait rows for it. Ignored for proimages and local.'),
                 color: z
                     .string()
                     .min(1)
                     .optional()
-                    .describe('Optional upstream color filter (e.g. "black_and_white"). Passed through as-is.'),
+                    .describe('Optional upstream color filter (e.g. "black_and_white"). Passed through as-is; ignored for local.'),
+                offset: z
+                    .number()
+                    .int()
+                    .min(0)
+                    .optional()
+                    .describe('source:"local" only: pass back a prior response\'s `next_offset` to continue. '
+                    + 'Ignored by the three proxy sources.'),
                 include_meta: INCLUDE_META_SCHEMA,
             },
             outputSchema: IMAGE_SEARCH_OUTPUT_SCHEMA,
             annotations: readOnly('Search Images'),
             handler: async ({ site_id, ...rest }) => withSiteRetry(pool, site_id, async (client, site) => withSiteMeta(await handleImageSearch({ client }, rest), site)),
         }),
-        // Task D1 (Image Sourcing) — write forward, mirrors library_insert.
-        // mutating() (writes to the Media Library) but NOT destructive() — it
-        // only creates, never deletes (Global Constraints, plan doc).
         defineTool({
             name: 'yootheme_builder_image_import',
-            description: 'Sideload a photo into the site\'s own Media Library. Accepts ANY public image '
-                + 'URL — it does NOT require a Library API key, so it still works when '
-                + 'image_search is unavailable (typically pass a `full_url` from '
-                + 'yootheme_builder_image_search). Returns `{imported:true, local_url}` where '
-                + 'local_url is a SITE-RELATIVE path (e.g. /wp-content/uploads/...). Bind it via '
-                + 'element_update_settings({props:{image: local_url}, merge:true}). A caught '
-                + 'import failure returns `{imported:false, reason}`, never a 500.',
+            description: 'Sideload a photo into the site\'s Media Library. Only Unsplash, Pexels and the '
+                + 'YOOtheme library CDN are accepted; other hosts are refused. Returns '
+                + '`{imported:true, local_url}`; shape is platform-specific: WordPress leads '
+                + 'with a slash (/wp-content/uploads/...), Joomla does NOT (images/yootheme/...). '
+                + 'Bind it VERBATIM via element_update_settings({props:{image: local_url}, ' +
+                'merge:true}). Give the address as `url` OR as `full_url`, the field name an ' +
+                'image_search row carries; one of the two is required. Identical re-imports ' +
+                'reuse the existing file in the current upload folder. Failures return ' +
+                '`{imported:false, reason, failure}`; `unavailable` = no url works now.',
             inputSchema: {
                 site_id: SITE_ID_SCHEMA,
                 url: z
                     .string()
                     .url()
+                    .optional()
                     .describe('The image URL to sideload (typically a full_url from '
                     + 'yootheme_builder_image_search). Downloads it into the site Media '
                     + 'Library and returns a local URL to bind via element_update_settings.'),
+                full_url: z
+                    .string()
+                    .url()
+                    .optional()
+                    .describe('Second name for `url` — the field name an image_search row carries, so a '
+                    + 'row can be passed on unchanged. Pass ONE of the two; two different '
+                    + 'values are refused rather than reconciled.'),
             },
             outputSchema: IMAGE_IMPORT_OUTPUT_SCHEMA,
             annotations: mutating('Import Image'),