@thinremote/thinr-cli 1.2.0-alpha.1 → 1.2.0

package/lib/mcp/tools-products.js

@@ -1,16 +1,41 @@
 // @ts-check
+import { Buffer } from 'node:buffer';
 import {
     getProducts,
+    getProduct,
+    createProduct,
+    productExists,
+    updateProduct,
     deleteProductWithStorage,
     installProductScript,
     removeProductScript,
     listProductScripts,
     readProductScript,
     getProductApi,
+    getProductProperties,
+    getProductProperty,
+    setProductProperty,
+    deleteProductProperty,
+    listDashboardMetrics,
+    upsertDashboardMetric,
+    removeDashboardMetric,
+    DASHBOARD_METRICS_PROPERTY,
+    findProductPlaybook,
+    listProductPlaybooks,
+    readProductPlaybook,
+    uploadProductPlaybook,
+    deleteProductPlaybook,
+    uploadFleetRunReport,
 } from '../product.js';
-import { getDevices, filterActiveDevices } from '../devices.js';
 import { createDeviceAPI } from '../device-api.js';
-import { runPool } from '../concurrency.js';
+import { TIMEOUTS } from '../constants.js';
+import { runProductFanOut } from '../product-orchestrator.js';
+import { requireConfig } from '../config.js';
+import { filterActiveDevices, getDevices } from '../devices.js';
+import { parsePlaybook } from '../playbook/loader.js';
+import { buildDryRunPlan, runPlaybook } from '../playbook/runner.js';
+import { DEFAULT_FAILURE_THRESHOLD, runFleetPlaybook } from '../playbook/fleet.js';
+import { listVariables, resolveVarScope } from '../playbook/vars.js';
 import { inputError } from '../errors.js';
 
 async function toolProducts(args) {
@@ -36,6 +61,104 @@ async function toolProducts(args) {
     };
 }
 
+async function toolProductCreate(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!/^[A-Za-z0-9._-]+$/.test(args.product)) {
+        throw inputError(
+            `Invalid product id "${args.product}" (allowed: letters, digits, dot, dash, underscore)`,
+        );
+    }
+    if (await productExists(args.product, args.user)) {
+        const err = new Error(`Product "${args.product}" already exists`);
+        err.code = 'already_exists';
+        throw err;
+    }
+
+    let iconSpec;
+    if (args.icon) {
+        if (!args.icon.source) throw inputError('icon.source is required when icon is set');
+        const type = args.icon.type || 'fa';
+        if (type !== 'fa' && type !== 'svg') {
+            throw inputError(`icon.type must be "fa" or "svg" (got "${type}")`);
+        }
+        iconSpec = {
+            type,
+            source: args.icon.source,
+            color: args.icon.color || '#000000',
+            background: args.icon.background || '#ffffff',
+        };
+    }
+
+    await createProduct(args.product, args.user, {
+        name: args.name,
+        description: args.description,
+        ...(iconSpec ? { icon: iconSpec } : {}),
+    });
+
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Created product "${args.product}"${args.name ? ` (${args.name})` : ''}.`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductUpdate(args) {
+    if (!args.product) throw inputError('product is required');
+
+    const patch = {};
+    if (args.name !== undefined) patch.name = args.name;
+    if (args.description !== undefined) patch.description = args.description;
+    if (args.enabled !== undefined) patch.enabled = !!args.enabled;
+
+    if (args.icon) {
+        if (!args.icon.source) throw inputError('icon.source is required when icon is set');
+        const type = args.icon.type || 'fa';
+        if (type !== 'fa' && type !== 'svg') {
+            throw inputError(`icon.type must be "fa" or "svg" (got "${type}")`);
+        }
+        // Fetch current config so the icon update doesn't clobber unrelated
+        // fields (`type`, custom dashboards, profile-side bits the API
+        // groups under config).
+        const current = await getProduct(args.product, args.user);
+        const config = { ...(current?.config || {}) };
+        config.icons = [
+            {
+                conditions: [],
+                icon: {
+                    type,
+                    source: args.icon.source,
+                    color: args.icon.color || '#000000',
+                    background: args.icon.background || '#ffffff',
+                },
+            },
+        ];
+        patch.config = config;
+    }
+
+    const fields = Object.keys(patch);
+    if (fields.length === 0) {
+        throw inputError(
+            'at least one of name, description, enabled, icon must be provided',
+        );
+    }
+
+    await updateProduct(args.product, args.user, patch);
+
+    const summary = fields
+        .map((f) => (f === 'config' ? 'icon' : f))
+        .join(', ');
+    return {
+        content: [
+            { type: 'text', text: `Updated product "${args.product}" (${summary}).` },
+        ],
+        isError: false,
+    };
+}
+
 async function toolProductDelete(args) {
     if (!args.product) throw inputError('product is required');
     const { steps } = await deleteProductWithStorage(args.product, args.user, {
@@ -82,7 +205,8 @@ async function toolProductScriptWrite(args) {
         name: args.name,
         content: args.content,
         user: args.user,
-        icon: args.icon,
+        input: args.input,
+        output: args.output,
     });
     const lines = [
         `Installed product script "${args.name}" on "${args.product}".`,
@@ -96,6 +220,135 @@ async function toolProductScriptWrite(args) {
     };
 }
 
+async function toolProductPropertyGet(args) {
+    if (!args.product) throw inputError('product is required');
+    if (args.property) {
+        const value = await getProductProperty(args.product, args.property, args.user);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(value, null, 2) }],
+            isError: false,
+        };
+    }
+    const list = await getProductProperties(args.product, args.user);
+    const names = Array.isArray(list) ? list.map((p) => p.property).filter(Boolean) : [];
+    return {
+        content: [{ type: 'text', text: names.length ? names.join('\n') : '(no properties)' }],
+        isError: false,
+    };
+}
+
+async function toolProductPropertySet(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.property) throw inputError('property is required');
+    if (args.value === undefined) throw inputError('value is required');
+    const saved = await setProductProperty(args.product, args.property, args.value, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Saved property "${saved.property}" on product "${saved.product || args.product}" (value: ${JSON.stringify(saved.value)})`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductPropertyDelete(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.property) throw inputError('property is required');
+    const removed = await deleteProductProperty(args.product, args.property, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: removed
+                    ? `Deleted property "${args.property}" from product "${args.product}".`
+                    : `Property "${args.property}" was not set on product "${args.product}".`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductMetricList(args) {
+    if (!args.product) throw inputError('product is required');
+    const metrics = await listDashboardMetrics(args.product, args.user);
+    if (metrics.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No dashboard metrics configured on product "${args.product}" (property "${DASHBOARD_METRICS_PROPERTY}" is empty).`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    const lines = metrics.map((m) => {
+        const parts = [
+            m.name,
+            `resource=${m.resource}`,
+            m.field ? `field=${m.field}` : null,
+            m.aggregation ? `agg=${m.aggregation}` : null,
+            m.visualization ? `viz=${m.visualization}` : null,
+            m.interval ? `interval=${m.interval}s` : null,
+        ].filter(Boolean);
+        return `  - ${parts.join('  ')}${m.label ? `  · ${m.label}` : ''}`;
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${metrics.length} metric(s) on "${args.product}":\n${lines.join('\n')}`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductMetricSet(args) {
+    if (!args.product) throw inputError('product is required');
+    const metric = {
+        name: args.name,
+        label: args.label,
+        resource: args.resource,
+        field: args.field,
+        aggregation: args.aggregation,
+        visualization: args.visualization,
+        interval: args.interval,
+        unit: args.unit,
+    };
+    for (const k of Object.keys(metric)) if (metric[k] === undefined) delete metric[k];
+    const { action, count } = await upsertDashboardMetric(args.product, metric, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Metric "${metric.name}" ${action} on product "${args.product}" (total: ${count}).`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductMetricDelete(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    const { action, count } = await removeDashboardMetric(args.product, args.name, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text:
+                    action === 'removed'
+                        ? `Removed metric "${args.name}" from product "${args.product}" (remaining: ${count}).`
+                        : `Metric "${args.name}" was not configured on product "${args.product}".`,
+            },
+        ],
+        isError: false,
+    };
+}
+
 async function toolProductScriptDelete(args) {
     const { steps } = await removeProductScript({
         product: args.product,
@@ -113,6 +366,333 @@ async function toolProductScriptDelete(args) {
     };
 }
 
+async function toolProductPlaybookList(args) {
+    if (!args.product) throw inputError('product is required');
+    const entries = await listProductPlaybooks(args.product, args.user);
+    if (entries.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No playbooks registered on product "${args.product}".`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    const lines = entries.map((e) => {
+        const desc = e.description ? ` — ${e.description}` : '';
+        return `  - ${e.name}${desc}  (${e.path})`;
+    });
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `${entries.length} playbook(s) on "${args.product}":\n${lines.join('\n')}`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductPlaybookRead(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    const content = await readProductPlaybook(args.product, args.name, args.user);
+    return {
+        content: [{ type: 'text', text: content }],
+        isError: false,
+    };
+}
+
+async function toolProductPlaybookWrite(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    if (typeof args.content !== 'string') throw inputError('content (YAML string) is required');
+    const result = await uploadProductPlaybook({
+        product: args.product,
+        name: args.name,
+        content: args.content,
+        description: args.description,
+        user: args.user,
+        skipValidation: !!args.skip_validation,
+    });
+    const header = `Playbook "${result.entry.name}" ${result.action} on product "${args.product}"${
+        result.replaced ? ' (replaced existing entry)' : ''
+    }.`;
+    const steps = result.steps.map((s) => `  - ${s}`);
+    return {
+        content: [{ type: 'text', text: [header, ...steps].join('\n') }],
+        isError: false,
+    };
+}
+
+async function toolProductPlaybookRun(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    if (!args.device) throw inputError('device is required (single-device only)');
+
+    const entry = await findProductPlaybook(args.product, args.name, args.user);
+    if (!entry) {
+        const available = await listProductPlaybooks(args.product, args.user);
+        throw inputError(
+            `Playbook "${args.name}" is not registered on product "${args.product}". Available: ${available.map((e) => e.name).join(', ') || '(none)'}`,
+        );
+    }
+
+    const content = await readProductPlaybook(args.product, args.name, args.user);
+    const pb = parsePlaybook(content, { sourcePath: `${args.name}.yaml` });
+
+    const rawVars =
+        args.vars && typeof args.vars === 'object' && !Array.isArray(args.vars) ? args.vars : {};
+
+    let resolvedScope;
+    try {
+        resolvedScope = resolveVarScope(pb, rawVars);
+    } catch (err) {
+        throw inputError(err.message);
+    }
+
+    pb.target.devices = [args.device];
+    pb.target.product = args.product;
+    pb.target.group = null;
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb, { overrides: rawVars });
+        const payload = {
+            dry_run: true,
+            product: args.product,
+            name: args.name,
+            device: args.device,
+            variables: listVariables(pb),
+            vars: resolvedScope,
+            steps: plan,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    const all = await getDevices({ product: args.product }, args.user);
+    const device =
+        all.find((d) => d.device === args.device) || {
+            device: args.device,
+            connection: { active: false },
+        };
+
+    const results = await runPlaybook(pb, [device], {
+        user: args.user,
+        concurrency: 1,
+        failFast: true,
+        checkMode: !!args.check,
+        overrides: rawVars,
+    });
+    const result = results[0];
+    const payload = {
+        product: args.product,
+        name: args.name,
+        device: args.device,
+        mode: args.check ? 'check' : 'apply',
+        ok: !!result?.ok,
+        result,
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: !result?.ok,
+    };
+}
+
+async function toolProductPlaybookRollout(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+
+    const batchSize =
+        Number.isFinite(args.batch_size) && args.batch_size > 0
+            ? Math.floor(args.batch_size)
+            : 5;
+    const failureThreshold =
+        args.failure_threshold === undefined || args.failure_threshold === null
+            ? DEFAULT_FAILURE_THRESHOLD
+            : Number(args.failure_threshold);
+    if (!Number.isFinite(failureThreshold) || failureThreshold < 0 || failureThreshold > 100) {
+        throw inputError('failure_threshold must be a number between 0 and 100');
+    }
+
+    const entry = await findProductPlaybook(args.product, args.name, args.user);
+    if (!entry) {
+        const available = await listProductPlaybooks(args.product, args.user);
+        throw inputError(
+            `Playbook "${args.name}" is not registered on product "${args.product}". Available: ${available.map((e) => e.name).join(', ') || '(none)'}`,
+        );
+    }
+
+    const content = await readProductPlaybook(args.product, args.name, args.user);
+    const pb = parsePlaybook(content, { sourcePath: `${args.name}.yaml` });
+
+    const rawVars =
+        args.vars && typeof args.vars === 'object' && !Array.isArray(args.vars) ? args.vars : {};
+
+    let resolvedScope;
+    try {
+        resolvedScope = resolveVarScope(pb, rawVars);
+    } catch (err) {
+        throw inputError(err.message);
+    }
+
+    const filters = {};
+    if (args.filter && typeof args.filter === 'object' && !Array.isArray(args.filter)) {
+        for (const [k, v] of Object.entries(args.filter)) {
+            if (!/^[A-Za-z0-9_]+$/.test(k)) {
+                throw inputError(`Invalid filter key "${k}"`);
+            }
+            filters[k] = v;
+        }
+    }
+
+    const baseFilter = { product: args.product };
+    if (args.group) baseFilter.asset_group = args.group;
+    Object.assign(baseFilter, filters);
+    let devices = await getDevices(baseFilter, args.user);
+    if (!args.include_offline) devices = filterActiveDevices(devices);
+
+    pb.target.devices = null;
+    pb.target.product = args.product;
+    pb.target.group = args.group || null;
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb, { overrides: rawVars });
+        const payload = {
+            dry_run: true,
+            product: args.product,
+            name: args.name,
+            fleet: true,
+            device_count: devices.length,
+            devices: devices.map((d) => d.device),
+            batch_size: batchSize,
+            failure_threshold: failureThreshold,
+            variables: listVariables(pb),
+            vars: resolvedScope,
+            steps: plan,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    if (devices.length === 0) {
+        const payload = {
+            product: args.product,
+            name: args.name,
+            fleet: true,
+            device_count: 0,
+            aborted: false,
+            summary: { attempted: 0, succeeded: 0, failed: 0, failureRate: 0 },
+            message: 'no matching devices',
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    const startedAt = new Date().toISOString();
+    const outcome = await runFleetPlaybook(pb, devices, {
+        user: args.user,
+        batchSize,
+        failureThreshold,
+        overrides: rawVars,
+        checkMode: !!args.check,
+    });
+    const finishedAt = new Date().toISOString();
+
+    const summary = {
+        attempted: outcome.attempted,
+        succeeded: outcome.succeeded,
+        failed: outcome.failed,
+        failureRate: outcome.failureRate,
+        total: devices.length,
+    };
+
+    const report = {
+        product: args.product,
+        name: args.name,
+        user: args.user || requireConfig().username,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime(),
+        mode: args.check ? 'check' : 'apply',
+        playbook: {
+            name: pb.name || null,
+            description: pb.description || null,
+            steps: pb.steps.length,
+        },
+        rollout: {
+            batchSize,
+            failureThreshold,
+            filters: Object.keys(filters).length > 0 ? filters : null,
+            group: args.group || null,
+            includeOffline: !!args.include_offline,
+        },
+        vars: resolvedScope,
+        summary,
+        aborted: outcome.aborted,
+        reason: outcome.reason,
+        batches: outcome.batches,
+        devices: outcome.results.map((r) => ({
+            device: r?.device,
+            ok: !!r?.ok,
+            skipped: !!r?.skipped,
+            error: r?.error || null,
+        })),
+    };
+
+    const upload = await uploadFleetRunReport({ product: args.product, report, user: args.user });
+
+    const payload = {
+        product: args.product,
+        name: args.name,
+        fleet: true,
+        mode: args.check ? 'check' : 'apply',
+        startedAt,
+        finishedAt,
+        batch_size: batchSize,
+        failure_threshold: failureThreshold,
+        device_count: devices.length,
+        batches: outcome.batches,
+        summary,
+        aborted: outcome.aborted,
+        reason: outcome.reason,
+        results: outcome.results,
+        report_uploaded: upload.ok,
+        report_path: upload.ok ? upload.path : null,
+        report_error: upload.ok ? null : upload.reason,
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: outcome.aborted || summary.failed > 0,
+    };
+}
+
+async function toolProductPlaybookDelete(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    const result = await deleteProductPlaybook({
+        product: args.product,
+        name: args.name,
+        user: args.user,
+    });
+    const header = result.removed
+        ? `Deleted playbook "${args.name}" from product "${args.product}".`
+        : `Playbook "${args.name}" was not registered on product "${args.product}".`;
+    const steps = result.steps.map((s) => `  - ${s}`);
+    return {
+        content: [{ type: 'text', text: [header, ...steps].join('\n') }],
+        isError: false,
+    };
+}
+
 /**
  * @typedef {{
  *   device: string,
@@ -126,22 +706,52 @@ async function toolProductScriptDelete(args) {
  * }} ExecEntry
  */
 
-async function toolProductExec(args) {
+async function toolProductWrite(args) {
     if (!args.product) throw inputError('product is required');
-    if (!args.command) throw inputError('command is required');
-    const concurrency =
-        Number.isFinite(args.concurrency) && args.concurrency > 0
-            ? Math.floor(args.concurrency)
-            : 10;
-    const timeout =
-        Number.isFinite(args.timeout) && args.timeout > 0 ? Math.floor(args.timeout) : 30;
-    const failFast = !!args.fail_fast;
-    const includeOffline = !!args.all;
+    if (typeof args.path !== 'string' || !args.path) throw inputError('path is required');
+    if (typeof args.content !== 'string') throw inputError('content (string) is required');
+    const payload = Buffer.from(args.content, 'utf8');
 
-    const filter = { productId: args.product };
-    if (args.group) filter.asset_group = args.group;
-    let devices = await getDevices(filter, args.user);
-    if (!includeOffline) devices = filterActiveDevices(devices);
+    const { devices, entries } = await runProductFanOut({
+        product: args.product,
+        group: args.group,
+        includeOffline: !!args.all,
+        user: args.user,
+        concurrency:
+            Number.isFinite(args.concurrency) && args.concurrency > 0
+                ? Math.floor(args.concurrency)
+                : 10,
+        failFast: !!args.fail_fast,
+        worker: async (device) => {
+            const t0 = Date.now();
+            try {
+                const api = createDeviceAPI(device.device, { user: args.user || undefined });
+                await api.writeFile(args.path, payload);
+                return {
+                    device: device.device,
+                    ok: true,
+                    bytes: payload.byteLength,
+                    durationMs: Date.now() - t0,
+                };
+            } catch (err) {
+                return {
+                    device: device.device,
+                    ok: false,
+                    bytes: 0,
+                    durationMs: Date.now() - t0,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+        skipped: (device, firstFailure) => ({
+            device: device.device,
+            ok: false,
+            bytes: 0,
+            durationMs: 0,
+            error: `skipped (fail-fast after ${firstFailure})`,
+        }),
+        isFailure: (entry) => !entry.ok,
+    });
 
     if (devices.length === 0) {
         const suffix = args.group ? `, group="${args.group}"` : '';
@@ -149,101 +759,111 @@ async function toolProductExec(args) {
             content: [
                 {
                     type: 'text',
-                    text: `No devices to run on (product="${args.product}"${suffix}).`,
+                    text: `No devices to upload to (product="${args.product}"${suffix}).`,
                 },
             ],
             isError: false,
         };
     }
 
-    const startTs = Date.now();
-    let aborted = false;
-    /** @type {string | null} */
-    let firstFailureDevice = null;
-
-    // Worker never throws: it returns a populated `ExecEntry` in every
-    // branch (success, non-zero exit, timeout, connection error, or
-    // "skipped" once fail-fast has triggered). That keeps the post-pool
-    // mapping trivial and sidesteps the `{ ok: true } | { ok: false }`
-    // union narrowing limitation with JSDoc types.
-    const poolResults = await runPool(devices, concurrency, async (device) => {
-        if (failFast && aborted) {
-            /** @type {ExecEntry} */
-            const skipped = {
-                device: device.device,
-                ok: false,
-                exitCode: null,
-                timedOut: false,
-                durationMs: 0,
-                stdout: '',
-                stderr: '',
-                error: `skipped (fail-fast after ${firstFailureDevice})`,
-            };
-            return skipped;
-        }
-        const perStart = Date.now();
-        let stdout = '';
-        let stderr = '';
-        /** @type {ExecEntry} */
-        let entry;
-        try {
-            const api = createDeviceAPI(device.device, { user: args.user || undefined });
-            const { exitCode, timedOut } = await api.execStream(args.command, {
-                timeout,
-                onStdout: (s) => {
-                    stdout += s;
-                },
-                onStderr: (s) => {
-                    stderr += s;
-                },
-            });
-            entry = {
-                device: device.device,
-                ok: !timedOut && exitCode === 0,
-                exitCode: exitCode ?? null,
-                timedOut: !!timedOut,
-                durationMs: Date.now() - perStart,
-                stdout,
-                stderr,
-            };
-        } catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            entry = {
-                device: device.device,
-                ok: false,
-                exitCode: null,
-                timedOut: false,
-                durationMs: Date.now() - perStart,
-                stdout,
-                stderr,
-                error: msg,
-            };
-        }
-        if (failFast && !entry.ok && !aborted) {
-            aborted = true;
-            firstFailureDevice = entry.device;
-        }
-        return entry;
-    });
+    const okCount = entries.filter((e) => e.ok).length;
+    const lines = [];
+    lines.push(
+        `Uploaded to ${okCount}/${entries.length} device(s) of product "${args.product}" (path: ${args.path}, ${payload.byteLength} bytes each).\n`,
+    );
+    for (const e of entries) {
+        lines.push(
+            `${e.device}  ${e.ok ? 'OK' : 'FAIL'}  ${e.durationMs}ms${e.ok ? '' : `  · ${e.error}`}`,
+        );
+    }
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        isError: okCount < entries.length,
+    };
+}
 
-    /** @type {ExecEntry[]} */
-    const entries = poolResults.map((r, i) => {
-        if (r && r.ok) return r.value;
-        // Defensive fallback — the worker above never throws, so this
-        // branch shouldn't trigger in practice.
-        return {
-            device: devices[i].device,
+async function toolProductExec(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.command) throw inputError('command is required');
+    const concurrency =
+        Number.isFinite(args.concurrency) && args.concurrency > 0
+            ? Math.floor(args.concurrency)
+            : 10;
+    const timeout =
+        Number.isFinite(args.timeout) && args.timeout > 0
+            ? Math.floor(args.timeout)
+            : TIMEOUTS.DEFAULT_EXEC_SECONDS;
+
+    const { devices, entries, durationMs } = await runProductFanOut({
+        product: args.product,
+        group: args.group,
+        includeOffline: !!args.all,
+        user: args.user,
+        concurrency,
+        failFast: !!args.fail_fast,
+        worker: async (device) => {
+            const perStart = Date.now();
+            let stdout = '';
+            let stderr = '';
+            try {
+                const api = createDeviceAPI(device.device, { user: args.user || undefined });
+                const { exitCode, timedOut } = await api.execStream(args.command, {
+                    timeout,
+                    onStdout: (s) => {
+                        stdout += s;
+                    },
+                    onStderr: (s) => {
+                        stderr += s;
+                    },
+                });
+                return {
+                    device: device.device,
+                    ok: !timedOut && exitCode === 0,
+                    exitCode: exitCode ?? null,
+                    timedOut: !!timedOut,
+                    durationMs: Date.now() - perStart,
+                    stdout,
+                    stderr,
+                };
+            } catch (err) {
+                return {
+                    device: device.device,
+                    ok: false,
+                    exitCode: null,
+                    timedOut: false,
+                    durationMs: Date.now() - perStart,
+                    stdout,
+                    stderr,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+            }
+        },
+        skipped: (device, firstFailure) => ({
+            device: device.device,
             ok: false,
             exitCode: null,
             timedOut: false,
             durationMs: 0,
             stdout: '',
             stderr: '',
-            error: 'unknown error',
-        };
+            error: `skipped (fail-fast after ${firstFailure})`,
+        }),
+        isFailure: (entry) => !entry.ok,
     });
 
-    const totalMs = Date.now() - startTs;
+    if (devices.length === 0) {
+        const suffix = args.group ? `, group="${args.group}"` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No devices to run on (product="${args.product}"${suffix}).`,
+                },
+            ],
+            isError: false,
+        };
+    }
+
     const okCount = entries.filter((e) => e.ok).length;
     const timedOutCount = entries.filter((e) => e.timedOut).length;
     const errorCount = entries.filter((e) => e.error).length;
@@ -267,7 +887,7 @@ async function toolProductExec(args) {
         if (e.stderr) lines.push(`stderr: ${e.stderr.trimEnd()}`);
     }
     lines.push(
-        `\nSummary: ${okCount} ok, ${failCount} failed, ${timedOutCount} timed out, ${errorCount} errored — ${totalMs}ms total`,
+        `\nSummary: ${okCount} ok, ${failCount} failed, ${timedOutCount} timed out, ${errorCount} errored — ${durationMs}ms total`,
     );
 
     const anyFailure = failCount + timedOutCount + errorCount > 0;
@@ -289,7 +909,122 @@ export const tools = [
             },
             required: [],
         },
-        handler: toolProducts,
+        handler: toolProducts,
+    },
+    {
+        name: 'thinr_product_create',
+        description: `Create a new product. The product ID is immutable — pick it carefully (letters, digits, dot, dash, underscore). Optionally set the display name, description and icon at creation time; otherwise sensible defaults apply (name = id, generic description, Font Awesome Linux icon).
+
+Failure mode: refuses to overwrite an existing product. Use thinr_product_update to change metadata on a product that already exists.
+
+Typical flow: thinr_products to discover what is already there, thinr_product_create to register the new one, thinr_product_script_write to attach scripts, thinr_product_metric_set to register dashboard metrics, thinr_device_set_product to assign devices.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: {
+                    type: 'string',
+                    description:
+                        'Stable product ID (letters, digits, dot, dash, underscore). Cannot be changed later.',
+                },
+                name: {
+                    type: 'string',
+                    description:
+                        'Display name shown across the platform UI. Defaults to the product ID.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Free-form description.',
+                },
+                icon: {
+                    type: 'object',
+                    description:
+                        "Optional icon. Pick `type: 'fa'` for a Font Awesome class or `type: 'svg'` for inline SVG markup. Defaults to a generic Linux icon.",
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['fa', 'svg'],
+                            description:
+                                "Icon kind: 'fa' (default) for Font Awesome class, 'svg' for inline SVG markup.",
+                        },
+                        source: {
+                            type: 'string',
+                            description:
+                                'Font Awesome class (e.g. "fab fa-linux", "fas fa-server") or full SVG markup including the `<svg>` wrapper.',
+                        },
+                        color: {
+                            type: 'string',
+                            description: 'Hex foreground color. Default: #000000.',
+                        },
+                        background: {
+                            type: 'string',
+                            description: 'Hex background color. Default: #ffffff.',
+                        },
+                    },
+                    required: ['source'],
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductCreate,
+    },
+    {
+        name: 'thinr_product_update',
+        description: `Update product metadata in place. Pass any subset of fields (\`name\`, \`description\`, \`enabled\`, \`icon\`) — only the supplied ones are modified, the rest are left untouched. Useful to set a friendlier display name shown across the platform UI, change the description, toggle the product on or off, or replace its icon.
+
+Icons accept Font Awesome classes (\`{ type: "fa", source: "fab fa-linux" }\`) or inline SVG markup (\`{ type: "svg", source: "<svg ...>...</svg>" }\`). When an icon is supplied, the current product config is fetched first so unrelated fields (type, profile, dashboards) are preserved.
+
+Does not change the product ID. To rename the ID itself, the product has to be recreated and devices reassigned.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID to update.' },
+                name: {
+                    type: 'string',
+                    description:
+                        'Display name shown across the platform UI (dashboards, lists, etc.).',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Free-form description.',
+                },
+                enabled: {
+                    type: 'boolean',
+                    description:
+                        'Enable or disable the product. Disabled products do not deliver scripts or buckets to devices.',
+                },
+                icon: {
+                    type: 'object',
+                    description:
+                        "Replace the product's icon. Pick `type: 'fa'` for a Font Awesome class or `type: 'svg'` for inline SVG markup.",
+                    properties: {
+                        type: {
+                            type: 'string',
+                            enum: ['fa', 'svg'],
+                            description:
+                                "Icon kind: 'fa' (default) for Font Awesome class, 'svg' for inline SVG markup.",
+                        },
+                        source: {
+                            type: 'string',
+                            description:
+                                'Font Awesome class (e.g. "fab fa-linux", "fas fa-server") or full SVG markup including the `<svg>` wrapper.',
+                        },
+                        color: {
+                            type: 'string',
+                            description: 'Hex foreground color. Default: #000000.',
+                        },
+                        background: {
+                            type: 'string',
+                            description: 'Hex background color. Default: #ffffff.',
+                        },
+                    },
+                    required: ['source'],
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductUpdate,
     },
     {
         name: 'thinr_product_delete',
@@ -345,12 +1080,22 @@ Product scripts are executable files kept in a per-product storage ("<product>")
     },
     {
         name: 'thinr_product_script_write',
-        description: `Install or replace a product-level script. Orchestrates everything transparently: creates the product's storage if missing, writes the generic index.js wrapper on first use, wires profile.code.storage, enables the product, uploads the script under scripts/<name>, and creates/updates the API resource so the script is immediately callable on any device of the product.
+        description: `Upsert a product-level script: installs a new script if the name is unused, replaces the existing one in place otherwise. The product must exist already — create it first with thinr_product_create. This tool only handles the script side: creates the product's storage if missing, writes the generic index.js wrapper on first use, wires profile.code.storage, enables the product, uploads the script under scripts/<name>, and creates/updates the API resource so the script is immediately callable on any device of the product.
+
+Naming convention: \`*_write\` denotes upsert, shared with every per-product leaf. The product container itself uses split thinr_product_create / thinr_product_update tools to make accidental overwrites of product metadata impossible.
 
 Script contract:
 - Any executable source. If the body starts with a shebang (#!/usr/bin/env python3, #!/bin/bash, …) the agent materializes it to a temp file and runs it with the declared interpreter. Without a shebang, the body runs through the shell (pipes, redirects, && all work).
-- The caller's optional "input" object is forwarded to the script on stdin as JSON. Parse with jq / json.load / JSON.parse.
-- Stdout/stderr/exit code are returned in the response.
+- Any object the caller sends when invoking the resource is forwarded to the script on stdin as JSON. Parse with jq / json.load / JSON.parse.
+- When \`output\` is true (default), stdout must be valid JSON; it is parsed server-side (parse_stdout) so the resource returns the decoded object, not the raw shell output.
+
+Pick \`input\` and \`output\` according to the resource shape:
+- output-only (e.g. stats): omit \`input\`, leave \`output\` at its default. Resource classifies as fn=3 (output); frontend renders only the typed output.
+- input+output (e.g. echo/transform): pass an \`input\` schema, leave \`output\` at its default. Resource classifies as fn=4 (input_output); frontend renders typed input fields AND the output.
+- input-only (e.g. notify, log): pass an \`input\` schema and set \`output: false\`. Resource classifies as fn=2 (input); frontend renders only the input form and the call replies empty.
+- run (e.g. ping, restart): omit \`input\` and set \`output: false\`. Resource classifies as fn=1 (run); just a button that fires the script.
+
+\`input\` schema shape: a plain object mapping field names to default values (e.g. { "threshold": 80, "label": "warm" }). Declaring it registers a template_payload on the request side so the frontend renders typed input fields with those defaults and callers can override each field when invoking the resource. Field names must match /^[A-Za-z_][A-Za-z0-9_]*$/; values may be string, number or boolean. Omit \`input\` for a free-form payload where any object passed by the caller flows straight to stdin without a declared schema.
 
 The file extension (.sh, .py, .js, …) is preserved in the storage for editor highlighting, but the API resource name is the stem without extension. So scripts/backup.sh is callable as the resource "backup".`,
         inputSchema: {
@@ -367,10 +1112,16 @@ The file extension (.sh, .py, .js, …) is preserved in the storage for editor h
                     description:
                         'Full script source code. Include a shebang to use a non-shell interpreter.',
                 },
-                icon: {
-                    type: 'string',
+                input: {
+                    type: 'object',
+                    description:
+                        'Optional input schema: plain object mapping field names to default values. Registers a typed template so the frontend renders input fields. Field names must match /^[A-Za-z_][A-Za-z0-9_]*$/. Values may be string, number or boolean. Omit for a free-form payload.',
+                    additionalProperties: true,
+                },
+                output: {
+                    type: 'boolean',
                     description:
-                        'Optional Font Awesome 5 icon class to use when the product is created (only applied on first write). Default: "fab fa-linux". Examples: "fab fa-apple", "fab fa-raspberry-pi", "fas fa-server".',
+                        'Whether the resource returns data. Default true: stdout is parsed as JSON and returned (and exposed as the resource output in the frontend). Set to false for fire-and-forget scripts — the resource replies empty and, combined with no input, classifies as "run".',
                 },
                 user: { type: 'string', description: 'API user' },
             },
@@ -378,6 +1129,50 @@ The file extension (.sh, .py, .js, …) is preserved in the storage for editor h
         },
         handler: toolProductScriptWrite,
     },
+    {
+        name: 'thinr_product_write',
+        description: `Upload a file to every active device of a product in parallel. Content is passed inline as a UTF-8 string — the same contract as thinr_write, just fanned out.
+
+Typical uses: rolling out a shared configuration file, pushing a small static asset, or seeding a script that devices load at boot. Offline devices are skipped by default; set \`all: true\` to attempt them too (they will typically fail fast with a connection error). \`concurrency\` bounds parallel uploads (default 10) and \`fail_fast\` stops dequeueing new devices after the first failure.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: {
+                    type: 'string',
+                    description: 'Product ID (discover with thinr_products).',
+                },
+                path: {
+                    type: 'string',
+                    description: 'Absolute path on each device where the file will be written.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'UTF-8 file content to write on every device.',
+                },
+                group: {
+                    type: 'string',
+                    description: 'Optional asset group filter.',
+                },
+                concurrency: {
+                    type: 'number',
+                    description: 'Max parallel uploads (default: 10).',
+                },
+                fail_fast: {
+                    type: 'boolean',
+                    description:
+                        'Stop dequeueing new devices as soon as one fails (default: false).',
+                },
+                all: {
+                    type: 'boolean',
+                    description:
+                        'Include offline devices (default: false — only active are targeted).',
+                },
+                user: { type: 'string', description: 'API user (admin impersonation).' },
+            },
+            required: ['product', 'path', 'content'],
+        },
+        handler: toolProductWrite,
+    },
     {
         name: 'thinr_product_exec',
         description: `Execute a shell command in parallel on every active device of a product, and return stdout, stderr, exit code and duration per device plus a consolidated summary.
@@ -441,4 +1236,330 @@ Prefer this over iterating \`thinr_exec\` device-by-device when you need to roll
         },
         handler: toolProductScriptDelete,
     },
+    {
+        name: 'thinr_product_property_get',
+        description: `Read a product-level property (not a device property). Product properties are structured JSON values attached to the product itself — typical uses include dashboard configuration, shared feature flags, or the list of dashboard metrics managed by thinr_product_metric_*. Call without \`property\` to list the names of every property configured on the product.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                property: {
+                    type: 'string',
+                    description:
+                        'Property name. Omit to list the names of all properties on the product.',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductPropertyGet,
+    },
+    {
+        name: 'thinr_product_property_set',
+        description: `Upsert a product-level property: creates the property if missing, overwrites it wholesale if it already exists. The value can be any JSON-serialisable shape (string, number, object, array). Prefer the higher-level thinr_product_metric_* tools when managing dashboard metrics — they encapsulate the property shape so you don't have to reconstruct it by hand.
+
+Naming convention: this tool follows the upsert pattern shared by every per-product leaf (\`*_set\`, \`*_write\`). Container-level operations (the product itself) split create and update into separate tools so a fresh registration cannot accidentally overwrite an existing product's metadata.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                property: { type: 'string', description: 'Property name to create or overwrite.' },
+                value: {
+                    description:
+                        'Any JSON-serialisable value (string, number, boolean, object, array).',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'property', 'value'],
+        },
+        handler: toolProductPropertySet,
+    },
+    {
+        name: 'thinr_product_property_delete',
+        description: `Delete a product-level property. Idempotent — returns success even if the property was not set.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                property: { type: 'string', description: 'Property name to delete.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'property'],
+        },
+        handler: toolProductPropertyDelete,
+    },
+    {
+        name: 'thinr_product_metric_list',
+        description: `List the dashboard metrics configured on a product. Each metric describes a value the dashboard should stream (resource to poll, aggregation, visualization, refresh interval). Metrics are stored under the \`${DASHBOARD_METRICS_PROPERTY}\` product property.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductMetricList,
+    },
+    {
+        name: 'thinr_product_metric_set',
+        description: `Upsert a dashboard metric on a product: creates a new entry if the \`name\` key is unused, overwrites the existing entry in place otherwise. Under the hood this edits the \`${DASHBOARD_METRICS_PROPERTY}\` product property — prefer this tool over thinr_product_property_set for dashboard metrics so the shape stays consistent.
+
+Typical flow: create the product first (thinr_product_create), write a script that returns the raw data (thinr_product_script_write), then register the metric so the dashboard knows how to surface it.
+
+Naming convention: \`*_set\` denotes upsert, shared with every per-product leaf. The product container itself uses split thinr_product_create / thinr_product_update tools to make accidental overwrites of product metadata impossible.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description:
+                        'Stable identifier for the metric (letters, digits, underscore, dash). Reusing a name updates the existing entry.',
+                },
+                label: {
+                    type: 'string',
+                    description: 'Human-readable label shown in the dashboard panel.',
+                },
+                resource: {
+                    type: 'string',
+                    description:
+                        'Product API resource the dashboard invokes per device to get the value (e.g. the stem of a product script).',
+                },
+                field: {
+                    type: 'string',
+                    description:
+                        'Dot-path into the resource response pointing at the numeric value to aggregate (e.g. "connections.devices"). Omit for scalar responses.',
+                },
+                aggregation: {
+                    type: 'string',
+                    description:
+                        'How to combine the per-device values across the fleet. Numeric reducers: "sum", "avg", "max", "min". "count" returns the number of devices reporting any non-null value, irrespective of value. "top" lists the values without counting repetitions. "none" returns the raw per-device array. "distribution" returns a flat object mapping each distinct reported value (coerced to string) to the number of devices reporting it — use it for categorical data such as agent version, release/branch, kernel, hostname pattern; it is the right choice when the question is "how is the fleet split across these values?". The output of "distribution" is an object value→count, not a number; the dashboard renders it as a sorted list with per-value percentages and a total row.',
+                    enum: ['sum', 'avg', 'max', 'min', 'count', 'top', 'none', 'distribution'],
+                },
+                visualization: {
+                    type: 'string',
+                    description:
+                        'Dashboard rendering hint. "kpi" (default) shows the aggregated value plus its age. "sparkline" renders the same value alongside a ▁▂▃▅▇ bar of the last ~32 samples, useful for metrics where the trend matters (throughput, connected devices). "list" pairs naturally with aggregation "distribution" — it lays out each value as its own row with count and percentage, plus a total. "bar" is reserved for future use and currently falls back to kpi.',
+                    enum: ['kpi', 'bar', 'sparkline', 'list'],
+                },
+                interval: {
+                    type: 'number',
+                    description:
+                        'Refresh interval in seconds the dashboard should subscribe with. Minimum: 1. Omit (or set to 0) to subscribe without a server-side poll — the stream then only relays values the device pushes on its own.',
+                },
+                unit: {
+                    type: 'string',
+                    description: 'Optional unit suffix for display (e.g. "%", "devices").',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name', 'resource'],
+        },
+        handler: toolProductMetricSet,
+    },
+    {
+        name: 'thinr_product_metric_delete',
+        description: `Remove a dashboard metric from a product by its \`name\`. If it was the last metric configured, the underlying \`${DASHBOARD_METRICS_PROPERTY}\` product property is removed entirely.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: { type: 'string', description: 'Metric name previously registered.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductMetricDelete,
+    },
+    {
+        name: 'thinr_product_playbook_list',
+        description: `List the playbooks registered on a product, with their description and storage path. Use this to discover available playbooks before reading or running them; pair with thinr_product_playbook_read when you need the full YAML of a specific entry. Returns an empty listing if the product has no \`playbooks\` index property yet.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductPlaybookList,
+    },
+    {
+        name: 'thinr_product_playbook_read',
+        description: `Return the raw YAML source of a single playbook stored on a product. Use this when you need the full document (to review it, edit and re-upload, or hand the content to thinr_playbook_run). For just the catalogue of available entries use thinr_product_playbook_list — it is cheaper and does not download each file.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description:
+                        'Playbook name as registered in the product index (letters, digits, underscore, dash — no extension).',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductPlaybookRead,
+    },
+    {
+        name: 'thinr_product_playbook_write',
+        description: `Upsert a playbook on a product from inline YAML: creates a new playbook if the name is unused, replaces the existing one in place otherwise. This is the upload step of the natural-language authoring flow: after the user describes what they want ("update the nginx package and restart the service on product X"), draft the YAML, iterate against thinr_playbook_validate until it is clean, then call this tool with the validated content.
+
+The YAML is re-validated here against the playbook schema; an invalid document fails fast with a descriptive error and nothing is written — never pass \`skip_validation: true\` to work around validation errors, fix the YAML instead. Uploads are two-phase and self-healing: the file is written under \`playbooks/<name>.yaml\` in the product storage first, then the entry is registered in the \`playbooks\` product property; if the index update fails on a brand-new playbook, the file is rolled back so the index never points at a missing file.
+
+Name rules: letters, digits, underscore, dash — no extension, no slashes. \`description\` is optional; when omitted, the playbook's own top-level \`description\` (if any) is recorded in the index. Author from scratch by calling thinr_playbook_schema first so the generated YAML matches the schema on the first draft.
+
+Naming convention: \`*_write\` denotes upsert, shared with every per-product leaf. The product container itself uses split thinr_product_create / thinr_product_update tools to make accidental overwrites of product metadata impossible.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description:
+                        'Playbook name (letters, digits, underscore, dash). Used as the key in the product index and as the filename under `playbooks/`.',
+                },
+                content: {
+                    type: 'string',
+                    description:
+                        'Full YAML source of the playbook. Validated before upload unless skip_validation is true.',
+                },
+                description: {
+                    type: 'string',
+                    description:
+                        "Optional description stored alongside the index entry. When omitted, falls back to the playbook's own `description` field.",
+                },
+                skip_validation: {
+                    type: 'boolean',
+                    description:
+                        'Escape hatch for rare cases where the schema cannot yet express a field the runtime already accepts (default: false). Do NOT set this to work around a validation error reported by thinr_playbook_validate — fix the YAML instead. An invalid document will still fail at run time.',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name', 'content'],
+        },
+        handler: toolProductPlaybookWrite,
+    },
+    {
+        name: 'thinr_product_playbook_run',
+        description: `Run a playbook stored on a product against a single device — the safe pre-flight before rolling out across a fleet. Downloads the playbook by name, seeds variables from the playbook's declared defaults, applies any overrides supplied in \`vars\`, validates them (unknown / non-overridable / wrong-type / missing-required all surface as errors), and executes every step against \`device\`.
+
+Pass \`dry_run: true\` to get the resolved plan without contacting the device. Pass \`check: true\` to contact the device read-only and report what each step would change. Overrides never mutate the stored playbook — they are per-invocation only. Use this tool before \`thinr_playbook_run\` (fleet mode) to validate behaviour on a single device first.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description: 'Playbook name as registered in the product index.',
+                },
+                device: {
+                    type: 'string',
+                    description: 'Target device ID (single-device only). Pick any device of the product.',
+                },
+                vars: {
+                    type: 'object',
+                    description:
+                        'Per-invocation variable overrides keyed by variable name. Values must match the declared type; unknown / non-overridable names are rejected.',
+                    additionalProperties: true,
+                },
+                dry_run: {
+                    type: 'boolean',
+                    description:
+                        'Return the resolved plan (variables + step summaries) without contacting the device (default: false).',
+                },
+                check: {
+                    type: 'boolean',
+                    description:
+                        'Contact the device read-only and report what each step would change, without writing (default: false).',
+                },
+                user: { type: 'string', description: 'API user (admin impersonation).' },
+            },
+            required: ['product', 'name', 'device'],
+        },
+        handler: toolProductPlaybookRun,
+    },
+    {
+        name: 'thinr_product_playbook_rollout',
+        description: `Roll a playbook stored on a product across every matching device, progressively and with safety rails. Devices are attempted in discrete batches of \`batch_size\`; a batch completes fully before the next starts. After each batch the cumulative failure rate is compared against \`failure_threshold\` — reaching it aborts the rollout without touching the remaining devices.
+
+Destructive: prefer running \`thinr_product_playbook_run\` on a single device first to validate behaviour. Variables resolve the same way (declared defaults + \`vars\` overrides, validated against declared types; unknown / non-overridable / missing-required all rejected). The rollout writes a persistent report to \`playbooks/runs/<timestamp>-<name>-<user>.json\` in the product file storage, capturing the resolved variables, per-device outcome, and stop reason if aborted — best-effort, a failed upload is reported but does not fail the rollout.
+
+Filtering: \`group\` restricts to an asset group; \`filter\` passes extra server-side key=value filters (repeatable keys only — letters/digits/underscore). By default only active devices are targeted; pass \`include_offline: true\` to attempt offline ones too.
+
+Use \`dry_run: true\` to get the resolved plan and the list of devices that would be targeted without contacting any of them. \`check: true\` contacts devices read-only and reports what each step would change, without writing.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description: 'Playbook name as registered in the product index.',
+                },
+                batch_size: {
+                    type: 'number',
+                    description:
+                        'Devices attempted in parallel per batch. Next batch starts only after the current one finishes. Default: 5.',
+                },
+                failure_threshold: {
+                    type: 'number',
+                    description: `Abort rollout when cumulative failure rate (percentage of attempted devices that failed) reaches this value. Must be between 0 and 100. Default: ${DEFAULT_FAILURE_THRESHOLD}.`,
+                },
+                group: {
+                    type: 'string',
+                    description:
+                        'Restrict to devices in this asset group. Combined with `filter` if both are set.',
+                },
+                filter: {
+                    type: 'object',
+                    description:
+                        'Extra server-side filters passed as query params when listing devices. Keys must match [A-Za-z0-9_]+. Typical uses: narrowing by device field.',
+                    additionalProperties: { type: 'string' },
+                },
+                include_offline: {
+                    type: 'boolean',
+                    description:
+                        'Include offline devices in the rollout (default: false — only active devices are attempted).',
+                },
+                vars: {
+                    type: 'object',
+                    description:
+                        'Per-invocation variable overrides applied to every device. Values must match the declared type; unknown / non-overridable names are rejected.',
+                    additionalProperties: true,
+                },
+                dry_run: {
+                    type: 'boolean',
+                    description:
+                        'Return the resolved plan and target devices without contacting any of them (default: false).',
+                },
+                check: {
+                    type: 'boolean',
+                    description:
+                        'Contact devices read-only and report what each step would change, without writing (default: false).',
+                },
+                user: { type: 'string', description: 'API user (admin impersonation).' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductPlaybookRollout,
+    },
+    {
+        name: 'thinr_product_playbook_delete',
+        description: `Remove a playbook from a product: first unregisters it from the \`playbooks\` index property, then deletes the underlying \`playbooks/<name>.yaml\` file from the product storage. Idempotent — calling it on a missing playbook reports success without erroring.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description: 'Playbook name previously registered on the product.',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductPlaybookDelete,
+    },
 ];