@assembly-js/app-foundation 0.0.12 → 0.0.14

package/CLAUDE.md

@@ -41,7 +41,7 @@ Assembly-specific gotchas live in `.claude/skills/<name>/SKILL.md`. Invoke them
 - `assembly-app-bridge-toast` — show toast notifications in the parent dashboard
 - `assembly-ai` — AI features via Assembly's OpenAI proxy (no API keys needed)
 - `assembly-storage` — app-private file uploads/downloads (not the portal Files module); the storage helpers come from `@assembly-js/app-foundation/server` — import, don't rewrite. POST only `{ fileName }` and store the returned key; never build the S3 key yourself.
-- `assembly-integrations` (present only when third-party integrations are enabled) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`; read before declaring an integration or writing a provider call — lists what's connectable and each provider's gotchas. Absent: managed OAuth isn't available, use `requiredSecrets` instead
+- `assembly-integrations` (present only when third-party integrations are enabled) — third-party providers (Slack, etc.) via `requiredIntegrations` + `getIntegration()`; read the skill and `.claude/skills/assembly-integrations/providers/<slug>.md` before declaring an integration or writing a provider call, and first when provider data displays wrongly (wrong format, raw IDs). Absent: managed OAuth isn't available, use `requiredSecrets` instead
 - `assembly-avatar-sub` — AvatarSub company badge wherever a client is rendered, including tables of your own records referencing a client; row duplication only for lists of clients
 - `assembly-user-company-selector` — UserCompanySelector for picking clients, internal users, companies
 - `assembly-forms` — react-hook-form + zod + Field component validation pattern

package/dist/airtable.d.ts

@@ -0,0 +1,71 @@
+import { type IntegrationClient } from './nango.js';
+export interface AirtableFieldSchema {
+    id: string;
+    name: string;
+    type: string;
+    options?: Record<string, unknown>;
+}
+export interface AirtableTableSchema {
+    id: string;
+    name: string;
+    primaryFieldId: string;
+    fields: AirtableFieldSchema[];
+}
+export interface AirtableRecord {
+    id: string;
+    createdTime?: string;
+    fields: Record<string, unknown>;
+}
+export interface AirtableFormattedField {
+    raw: unknown;
+    display: string;
+}
+export interface AirtableFormattedRecord {
+    id: string;
+    createdTime?: string;
+    fields: Record<string, AirtableFormattedField>;
+}
+export type AirtableSchemaResult = {
+    ok: true;
+    schema: AirtableTableSchema;
+} | {
+    ok: false;
+    error: {
+        code: string;
+        provider: string;
+    };
+};
+export interface FormatAirtableRecordsOpts {
+    /** The getIntegration('airtable') client. Required to resolve linked-record labels. */
+    client?: IntegrationClient;
+    /** Base the records came from. Required to resolve linked-record labels. */
+    baseId?: string;
+}
+/**
+ * One table's schema from `get-base-schema` (fields with id, name, type,
+ * options). Memoized on the client for the rest of this request so a render
+ * that formats several pages does not refetch the base. Failures come back as
+ * `{ ok: false, error }` — ConnectorError does not survive a Server Action
+ * boundary.
+ *
+ * Server-side only: pass the client from `getIntegration('airtable')`.
+ */
+export declare function getAirtableTableSchema(client: IntegrationClient, baseId: string, tableIdOrName: string): Promise<AirtableSchemaResult>;
+/**
+ * For each record, return raw + display per field so sorts/edits keep machine
+ * values. Formats percent / currency / number / date / dateTime / duration from
+ * field options; resolves `multipleRecordLinks` ID arrays to the linked table's
+ * primary-field labels (one `list-records` per linked table, chunked
+ * `RECORD_ID()` filter, primary field only). Computed fields (formula / rollup /
+ * multipleLookupValues) format by their `options.result` inner type, reusing the
+ * same typed formatters; arrays (lookups) format each element and join. A cell
+ * that comes back as an error-state object (`{state:"error",errorType:...}`,
+ * `{error:"#ERROR!"}`) or a numeric special value (`{specialValue:"NaN"|"Infinity"}`)
+ * never reaches display as raw JSON — display becomes an em dash, raw is untouched.
+ * Unknown types pass through; arrays join with ", ". Linked-table failures degrade
+ * to the raw ID and never throw the render.
+ *
+ * Server-side only when `opts.client` is set (label lookup goes through the
+ * broker). Omit client/baseId to format in-memory types only.
+ */
+export declare function formatAirtableRecords(records: AirtableRecord[], schema: AirtableTableSchema, opts?: FormatAirtableRecordsOpts): Promise<AirtableFormattedRecord[]>;

package/dist/airtable.js

@@ -0,0 +1,561 @@
+import { ConnectorError } from './nango.js';
+// Airtable GET list-records puts filterByFormula on the query string. ~40
+// RECORD_ID() clauses stay comfortably under typical URL/formula limits
+// (a page of records can easily collect more linked IDs than that).
+const AIRTABLE_LINKED_ID_CHUNK = 40;
+// Keyed by the per-request client object so a warm serverless isolate cannot
+// serve another invocation's schema. Repeated calls in one render (same client)
+// share the in-flight get-base-schema promise.
+const baseSchemaByClient = new WeakMap();
+/**
+ * One table's schema from `get-base-schema` (fields with id, name, type,
+ * options). Memoized on the client for the rest of this request so a render
+ * that formats several pages does not refetch the base. Failures come back as
+ * `{ ok: false, error }` — ConnectorError does not survive a Server Action
+ * boundary.
+ *
+ * Server-side only: pass the client from `getIntegration('airtable')`.
+ */
+export async function getAirtableTableSchema(client, baseId, tableIdOrName) {
+    const wanted = tableIdOrName.trim();
+    if (!baseId.trim() || !wanted) {
+        return { ok: false, error: { code: 'invalid_request', provider: 'airtable' } };
+    }
+    const loaded = await loadBaseSchema(client, baseId);
+    if (!loaded.ok)
+        return loaded;
+    const table = loaded.tables.find((t) => t.id === wanted || t.name === wanted);
+    if (!table) {
+        return { ok: false, error: { code: 'table_not_found', provider: 'airtable' } };
+    }
+    return { ok: true, schema: table };
+}
+/**
+ * For each record, return raw + display per field so sorts/edits keep machine
+ * values. Formats percent / currency / number / date / dateTime / duration from
+ * field options; resolves `multipleRecordLinks` ID arrays to the linked table's
+ * primary-field labels (one `list-records` per linked table, chunked
+ * `RECORD_ID()` filter, primary field only). Computed fields (formula / rollup /
+ * multipleLookupValues) format by their `options.result` inner type, reusing the
+ * same typed formatters; arrays (lookups) format each element and join. A cell
+ * that comes back as an error-state object (`{state:"error",errorType:...}`,
+ * `{error:"#ERROR!"}`) or a numeric special value (`{specialValue:"NaN"|"Infinity"}`)
+ * never reaches display as raw JSON — display becomes an em dash, raw is untouched.
+ * Unknown types pass through; arrays join with ", ". Linked-table failures degrade
+ * to the raw ID and never throw the render.
+ *
+ * Server-side only when `opts.client` is set (label lookup goes through the
+ * broker). Omit client/baseId to format in-memory types only.
+ */
+export async function formatAirtableRecords(records, schema, opts = {}) {
+    const list = Array.isArray(records) ? records : [];
+    const fieldsByKey = indexFields(schema);
+    let labelsByTable = new Map();
+    try {
+        labelsByTable = await loadLinkedLabels(list, schema, opts);
+    }
+    catch {
+        // Linked-table I/O is best-effort; typed-column formatting still runs.
+    }
+    return list.map((record) => {
+        const fields = {};
+        for (const [key, raw] of Object.entries(record.fields ?? {})) {
+            const field = fieldsByKey.get(key);
+            fields[key] = {
+                raw,
+                display: displayForField(raw, field, labelsByTable),
+            };
+        }
+        return {
+            id: record.id,
+            ...(record.createdTime !== undefined ? { createdTime: record.createdTime } : {}),
+            fields,
+        };
+    });
+}
+function loadBaseSchema(client, baseId) {
+    let byBase = baseSchemaByClient.get(client);
+    if (!byBase) {
+        byBase = new Map();
+        baseSchemaByClient.set(client, byBase);
+    }
+    const cached = byBase.get(baseId);
+    if (cached)
+        return cached;
+    const pending = fetchBaseSchema(client, baseId).then((result) => {
+        if (!result.ok)
+            byBase.delete(baseId);
+        return result;
+    }, (err) => {
+        byBase.delete(baseId);
+        throw err;
+    });
+    byBase.set(baseId, pending);
+    return pending;
+}
+async function fetchBaseSchema(client, baseId) {
+    try {
+        const raw = await client.action('get-base-schema', { baseId });
+        return { ok: true, tables: parseTables(raw?.tables) };
+    }
+    catch (err) {
+        if (err instanceof ConnectorError) {
+            return { ok: false, error: { code: err.code, provider: err.provider } };
+        }
+        throw err;
+    }
+}
+function parseTables(raw) {
+    if (!Array.isArray(raw))
+        return [];
+    const tables = [];
+    for (const item of raw) {
+        const table = asTable(item);
+        if (table)
+            tables.push(table);
+    }
+    return tables;
+}
+function asTable(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const t = raw;
+    if (typeof t.id !== 'string' || typeof t.name !== 'string')
+        return null;
+    const fields = [];
+    if (Array.isArray(t.fields)) {
+        for (const item of t.fields) {
+            const field = asField(item);
+            if (field)
+                fields.push(field);
+        }
+    }
+    return {
+        id: t.id,
+        name: t.name,
+        primaryFieldId: typeof t.primaryFieldId === 'string' ? t.primaryFieldId : '',
+        fields,
+    };
+}
+function asField(raw) {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const f = raw;
+    if (typeof f.id !== 'string' || typeof f.name !== 'string' || typeof f.type !== 'string') {
+        return null;
+    }
+    const options = f.options && typeof f.options === 'object' && !Array.isArray(f.options)
+        ? f.options
+        : undefined;
+    return { id: f.id, name: f.name, type: f.type, ...(options ? { options } : {}) };
+}
+function indexFields(schema) {
+    const map = new Map();
+    for (const field of schema?.fields ?? []) {
+        map.set(field.name, field);
+        map.set(field.id, field);
+    }
+    return map;
+}
+async function loadLinkedLabels(records, schema, opts) {
+    const byTable = new Map();
+    const client = opts.client;
+    const baseId = opts.baseId?.trim();
+    if (!client || !baseId)
+        return byTable;
+    const linkFields = (schema.fields ?? []).filter((field) => field.type === 'multipleRecordLinks' && linkedTableIdOf(field));
+    if (linkFields.length === 0)
+        return byTable;
+    const idsByTable = new Map();
+    for (const field of linkFields) {
+        const tableId = linkedTableIdOf(field);
+        if (!tableId)
+            continue;
+        let ids = idsByTable.get(tableId);
+        if (!ids) {
+            ids = new Set();
+            idsByTable.set(tableId, ids);
+        }
+        for (const record of records) {
+            for (const id of recordIdsIn(record.fields?.[field.name] ?? record.fields?.[field.id])) {
+                ids.add(id);
+            }
+        }
+    }
+    await Promise.all([...idsByTable.entries()].map(async ([tableId, ids]) => {
+        if (ids.size === 0)
+            return;
+        const labels = await fetchLinkedLabels(client, baseId, tableId, [...ids]);
+        byTable.set(tableId, labels);
+    }));
+    return byTable;
+}
+async function fetchLinkedLabels(client, baseId, tableId, ids) {
+    const labels = new Map();
+    let primaryName;
+    try {
+        const linked = await getAirtableTableSchema(client, baseId, tableId);
+        if (linked.ok)
+            primaryName = primaryFieldName(linked.schema);
+    }
+    catch {
+        // Without the primary field name a successful list-records would still
+        // guess a column — keep raw IDs instead.
+    }
+    if (!primaryName)
+        return labels;
+    const safeIds = ids.filter((id) => AIRTABLE_RECORD_ID_RE.test(id));
+    for (const chunk of chunkIds(safeIds, AIRTABLE_LINKED_ID_CHUNK)) {
+        try {
+            let offset;
+            do {
+                const page = await client.action('list-records', {
+                    baseId,
+                    tableIdOrName: tableId,
+                    filterByFormula: recordIdFormula(chunk),
+                    fields: [primaryName],
+                    pageSize: 100,
+                    ...(offset ? { offset } : {}),
+                });
+                for (const rec of page.records ?? []) {
+                    const label = labelFromPrimary(rec.fields?.[primaryName]);
+                    if (label)
+                        labels.set(rec.id, label);
+                }
+                offset = typeof page.offset === 'string' && page.offset ? page.offset : undefined;
+            } while (offset);
+        }
+        catch {
+            // Rate-limit / ConnectorError / a deleted-table 404: keep labels from
+            // earlier chunks and leave the rest as raw IDs. Never fail the render.
+        }
+    }
+    return labels;
+}
+// Cell-level shapes Airtable's computed fields (formula/lookup/rollup) can
+// return instead of a value: an error state, or a numeric special value.
+// Never let one of these reach display as a raw JSON blob — the guard runs
+// ahead of every field-type branch, including types this file never learns.
+const EM_DASH = '—';
+function isErrorCell(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const obj = value;
+    if (obj.state === 'error')
+        return true;
+    if (typeof obj.errorType === 'string' && obj.errorType)
+        return true;
+    // Airtable's classic `{error: "#ERROR!"}` cell shape.
+    if (typeof obj.error === 'string' && obj.error)
+        return true;
+    return false;
+}
+function isSpecialValueCell(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const obj = value;
+    return obj.specialValue === 'NaN' || obj.specialValue === 'Infinity';
+}
+function isGuardedCell(value) {
+    return isErrorCell(value) || isSpecialValueCell(value);
+}
+/** The `options.result` a formula/rollup/lookup field carries: what its computed value looks like. */
+function resultTypeOf(options) {
+    const result = options?.result;
+    if (!result || typeof result !== 'object' || Array.isArray(result))
+        return undefined;
+    const r = result;
+    if (typeof r.type !== 'string' || !r.type)
+        return undefined;
+    const nestedOptions = r.options && typeof r.options === 'object' && !Array.isArray(r.options)
+        ? r.options
+        : undefined;
+    return { type: r.type, ...(nestedOptions ? { options: nestedOptions } : {}) };
+}
+/**
+ * Formats a formula/rollup/lookup value by its inner result type, reusing the
+ * typed formatters below. Arrays (lookups, array-valued rollups) format each
+ * element and join for display. Guards error/special-value cells at every
+ * level so one bad element never blanks the whole row.
+ */
+function formatByResultType(raw, result) {
+    if (isGuardedCell(raw))
+        return EM_DASH;
+    if (Array.isArray(raw)) {
+        return raw
+            .map((item) => formatByResultType(item, result))
+            .filter((s) => s !== '')
+            .join(', ');
+    }
+    if (!result)
+        return displayUnknown(raw);
+    switch (result.type) {
+        case 'percent':
+            return formatPercent(raw, optionInt(result.options, 'precision') ?? 0);
+        case 'currency':
+            return formatCurrency(raw, optionString(result.options, 'symbol') ?? '', optionInt(result.options, 'precision') ?? 2);
+        case 'number':
+            return formatNumber(raw, optionInt(result.options, 'precision') ?? 0);
+        case 'date':
+            return formatDateValue(raw, dateFormatName(result.options), undefined);
+        case 'dateTime':
+            return formatDateValue(raw, dateFormatName(result.options), timeFormatName(result.options));
+        case 'duration':
+            return formatDuration(raw, optionString(result.options, 'durationFormat') ?? 'h:mm');
+        default:
+            return displayUnknown(raw);
+    }
+}
+function displayForField(raw, field, labelsByTable) {
+    // Value-shape guard first — applies regardless of field type or whether
+    // the field is even in the schema.
+    if (isGuardedCell(raw))
+        return EM_DASH;
+    if (!field)
+        return displayUnknown(raw);
+    switch (field.type) {
+        case 'percent':
+            return formatPercent(raw, optionInt(field.options, 'precision') ?? 0);
+        case 'currency':
+            return formatCurrency(raw, optionString(field.options, 'symbol') ?? '', optionInt(field.options, 'precision') ?? 2);
+        case 'number':
+            return formatNumber(raw, optionInt(field.options, 'precision') ?? 0);
+        case 'date':
+            return formatDateValue(raw, dateFormatName(field.options), undefined);
+        case 'dateTime':
+            return formatDateValue(raw, dateFormatName(field.options), timeFormatName(field.options));
+        case 'duration':
+            return formatDuration(raw, optionString(field.options, 'durationFormat') ?? 'h:mm');
+        case 'multipleRecordLinks': {
+            const tableId = linkedTableIdOf(field);
+            const labels = tableId ? labelsByTable.get(tableId) : undefined;
+            const ids = recordIdsIn(raw);
+            if (ids.length === 0)
+                return displayUnknown(raw);
+            return ids.map((id) => labels?.get(id) ?? id).join(', ');
+        }
+        case 'formula':
+        case 'rollup':
+        case 'multipleLookupValues':
+        case 'lookup':
+            return formatByResultType(raw, resultTypeOf(field.options));
+        default:
+            return displayUnknown(raw);
+    }
+}
+function formatPercent(raw, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    return `${formatFixed(n * 100, precision)}%`;
+}
+function formatCurrency(raw, symbol, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    const abs = formatFixed(Math.abs(n), precision);
+    const sign = n < 0 ? '-' : '';
+    return `${sign}${symbol}${abs}`;
+}
+function formatNumber(raw, precision) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    return formatFixed(n, precision);
+}
+function formatDateValue(raw, dateName, timeName) {
+    if (typeof raw !== 'string' || !raw.trim())
+        return displayUnknown(raw);
+    const parts = parseAirtableDate(raw);
+    if (!parts)
+        return raw;
+    const date = formatDateParts(parts, dateName ?? 'local');
+    if (!timeName || parts.hours === undefined)
+        return date;
+    return `${date} ${formatTimeParts(parts, timeName)}`;
+}
+function formatDuration(raw, durationFormat) {
+    const n = asFiniteNumber(raw);
+    if (n === null)
+        return displayUnknown(raw);
+    const negative = n < 0;
+    const abs = Math.abs(n);
+    const hours = Math.floor(abs / 3600);
+    const minutes = Math.floor((abs % 3600) / 60);
+    const seconds = abs % 60;
+    let body;
+    switch (durationFormat) {
+        case 'h:mm:ss':
+            body = `${hours}:${pad2(minutes)}:${pad2(Math.floor(seconds))}`;
+            break;
+        case 'h:mm:ss.s':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 1).padStart(4, '0')}`;
+            break;
+        case 'h:mm:ss.ss':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 2).padStart(5, '0')}`;
+            break;
+        case 'h:mm:ss.sss':
+            body = `${hours}:${pad2(minutes)}:${formatFixed(seconds, 3).padStart(6, '0')}`;
+            break;
+        case 'h:mm':
+        default:
+            body = `${hours}:${pad2(minutes)}`;
+            break;
+    }
+    return negative ? `-${body}` : body;
+}
+function displayUnknown(raw) {
+    if (raw == null || raw === '')
+        return '';
+    if (Array.isArray(raw)) {
+        return raw.map(displayUnknown).filter(Boolean).join(', ');
+    }
+    if (typeof raw === 'string')
+        return raw;
+    if (typeof raw === 'number' && Number.isFinite(raw))
+        return String(raw);
+    if (typeof raw === 'boolean')
+        return raw ? 'checked' : '';
+    if (typeof raw === 'object') {
+        const obj = raw;
+        if (typeof obj.name === 'string' && obj.name)
+            return obj.name;
+        if (typeof obj.filename === 'string' && obj.filename)
+            return obj.filename;
+        if (typeof obj.url === 'string' && obj.url)
+            return obj.url;
+    }
+    return '';
+}
+function recordIdsIn(raw) {
+    if (typeof raw === 'string' && raw.startsWith('rec'))
+        return [raw];
+    if (!Array.isArray(raw))
+        return [];
+    const ids = [];
+    for (const item of raw) {
+        if (typeof item === 'string' && item.startsWith('rec'))
+            ids.push(item);
+    }
+    return ids;
+}
+function labelFromPrimary(raw) {
+    const text = displayUnknown(raw).trim();
+    return text;
+}
+function primaryFieldName(schema) {
+    const match = schema.fields.find((f) => f.id === schema.primaryFieldId);
+    return match?.name;
+}
+function linkedTableIdOf(field) {
+    return optionString(field.options, 'linkedTableId');
+}
+// Airtable record IDs are strictly alphanumeric (rec + 14+ chars). Rather than
+// escape quotes/backslashes for formula interpolation, reject anything else —
+// a non-conforming id keeps its raw value like every other lookup failure.
+const AIRTABLE_RECORD_ID_RE = /^[A-Za-z0-9]+$/;
+function recordIdClause(id) {
+    return `RECORD_ID()='${id}'`;
+}
+function recordIdFormula(ids) {
+    if (ids.length === 1)
+        return recordIdClause(ids[0]);
+    return `OR(${ids.map(recordIdClause).join(',')})`;
+}
+function chunkIds(ids, size) {
+    const chunks = [];
+    for (let i = 0; i < ids.length; i += size) {
+        chunks.push(ids.slice(i, i + size));
+    }
+    return chunks;
+}
+function optionString(options, key) {
+    const value = options?.[key];
+    return typeof value === 'string' && value ? value : undefined;
+}
+function optionInt(options, key) {
+    const value = options?.[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function nestedFormatName(options, key) {
+    const nested = options?.[key];
+    if (!nested || typeof nested !== 'object' || Array.isArray(nested))
+        return undefined;
+    const name = nested.name;
+    return typeof name === 'string' && name ? name : undefined;
+}
+function dateFormatName(options) {
+    return nestedFormatName(options, 'dateFormat');
+}
+function timeFormatName(options) {
+    return nestedFormatName(options, 'timeFormat');
+}
+function asFiniteNumber(raw) {
+    return typeof raw === 'number' && Number.isFinite(raw) ? raw : null;
+}
+function formatFixed(n, precision) {
+    const digits = Number.isInteger(precision) && precision >= 0 ? precision : 0;
+    const factor = 10 ** digits;
+    return (Math.round(n * factor) / factor).toFixed(digits);
+}
+const MONTHS = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+function parseAirtableDate(value) {
+    const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+    if (dateOnly) {
+        return {
+            year: Number(dateOnly[1]),
+            month: Number(dateOnly[2]),
+            day: Number(dateOnly[3]),
+        };
+    }
+    const parsed = new Date(value);
+    if (Number.isNaN(parsed.getTime()))
+        return null;
+    return {
+        year: parsed.getUTCFullYear(),
+        month: parsed.getUTCMonth() + 1,
+        day: parsed.getUTCDate(),
+        hours: parsed.getUTCHours(),
+        minutes: parsed.getUTCMinutes(),
+        seconds: parsed.getUTCSeconds(),
+    };
+}
+function formatDateParts(parts, name) {
+    switch (name) {
+        case 'iso':
+            return `${parts.year}-${pad2(parts.month)}-${pad2(parts.day)}`;
+        case 'european':
+            return `${parts.day}/${parts.month}/${parts.year}`;
+        case 'friendly':
+            return `${MONTHS[parts.month - 1] ?? parts.month} ${parts.day}, ${parts.year}`;
+        case 'us':
+        case 'local':
+        default:
+            return `${parts.month}/${parts.day}/${parts.year}`;
+    }
+}
+function formatTimeParts(parts, name) {
+    const hours = parts.hours ?? 0;
+    const minutes = pad2(parts.minutes ?? 0);
+    if (name === '24hour')
+        return `${pad2(hours)}:${minutes}`;
+    const suffix = hours >= 12 ? 'pm' : 'am';
+    const hour12 = hours % 12 === 0 ? 12 : hours % 12;
+    return `${hour12}:${minutes}${suffix}`;
+}
+function pad2(n) {
+    return String(n).padStart(2, '0');
+}

package/dist/nango.d.ts

@@ -1,5 +1,5 @@
 import { type ResourceFieldMap, type ResourcePage } from './resource-resolution.js';
-export type Provider = 'slack' | 'gmail' | 'google-calendar' | 'google-drive' | 'google-sheet' | 'hubspot' | 'salesforce' | 'notion' | 'linear' | 'stripe' | 'github';
+export type Provider = 'slack' | 'airtable' | 'gmail' | 'google-calendar' | 'google-drive' | 'google-sheet' | 'hubspot' | 'salesforce' | 'notion' | 'linear' | 'stripe' | 'github';
 export type ConnectorErrorCode = 'app_key_required' | 'provider_not_declared' | 'connection_required' | 'needs_reauth' | 'needs_reauth_scope' | 'connection_throttled' | 'connector_unavailable' | 'action_failed' | 'invalid_request';
 export interface ConnectionStatus {
     provider: string;

package/dist/nango.js

@@ -122,8 +122,9 @@ export async function getIntegration(provider) {
         delete: withMethod('DELETE'),
         // Synchronously triggers a pre-built Nango Action and returns its normalized
         // result inline as JSON. The whole `input` object is the action input.
-        // The available actions are listed in the assembly-integrations skill —
-        // never guess a name not on that list (an unknown name fails at runtime).
+        // Action names live in the assembly-integrations skill index; signatures
+        // live only in providers/<slug>.md — never guess a name or input shape
+        // (an unknown name fails at runtime).
         // A script-level failure throws ConnectorError with code 'action_failed'
         // and the provider error in `detail`.
         action: async (name, input) => {

package/dist/server.d.ts

@@ -4,6 +4,7 @@ export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
+export * from './airtable.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/dist/server.js

@@ -8,6 +8,7 @@ export * from './auth.js';
 export * from './client-access.js';
 export * from './mint-bearer.js';
 export * from './nango.js';
+export * from './airtable.js';
 export * from './app-storage.js';
 export * from './labels.js';
 export * from './notifications.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@assembly-js/app-foundation",
-  "version": "0.0.12",
+  "version": "0.0.14",
   "description": "Versioned foundation helpers and build context for Assembly generated apps",
   "type": "module",
   "files": [

package/render-context.mjs

@@ -82,9 +82,12 @@ export function renderFeatureGates(content, features) {
 // Replaces each catalog token with the markdown Go rendered for it. A token with no
 // entry is left alone: the config omits catalogs when the workspace cannot reach a
 // provider, and the surrounding prose is written to read correctly either way.
+// Keys are the full token strings, including per-slug markers
+// (`<!-- ASSEMBLY_ACTIONS:slack -->`) alongside the legacy globals.
 export function substituteCatalogs(content, catalogs) {
   let out = content;
   for (const [token, markdown] of Object.entries(catalogs ?? {})) {
+    if (!token) continue;
     out = out.split(token).join(markdown);
   }
   return out;

package/skills/assembly-integrations/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: assembly-integrations
-description: Use BEFORE declaring requiredIntegrations in .assembly/app.json or calling getIntegration() from @assembly-js/app-foundation/server (Slack + other providers). Covers manifest declaration, the broker client, per-provider gotchas (pagination, IDs vs names, membership), ConnectorError handling.
+description: Use BEFORE declaring requiredIntegrations in .assembly/app.json or calling getIntegration() from @assembly-js/app-foundation/server, and when provider data displays wrongly (wrong format, raw IDs). Covers manifest declaration and the connector broker client. Read .claude/skills/assembly-integrations/providers/<slug>.md before any action() call for that provider and first when displayed provider data looks wrong.
 ---
 
 ## How it works
@@ -21,7 +21,7 @@ The flow:
 
 The Nango whitelist takes priority. If the provider is one of the supported providers below, always use `requiredIntegrations` — it gives the admin a one-click OAuth flow and Assembly manages token refresh for you.
 
-Supported providers (the v1 whitelist):
+Supported providers (the v1 whitelist). Action signatures exist only in the provider docs; never invent an action name:
 
 <!-- ASSEMBLY_PROVIDERS -->
 
@@ -40,7 +40,7 @@ Add a top-level `requiredIntegrations` array to `.assembly/app.json`. Each entry
 ```
 
 - `provider` must be one of the supported keys above.
-- `scopes` lists the provider's OAuth scopes; request the minimum your app needs.
+- `scopes` lists the provider's OAuth scopes; request the minimum your app needs. Per-provider scope recommendations live in that provider's doc.
 
 ## Calling the API
 
@@ -52,65 +52,19 @@ import { getIntegration } from '@assembly-js/app-foundation/server';
 
 `getIntegration(provider)` resolves to a thin client:
 
-- **`action(name, input)`** — synchronously trigger a pre-built Nango Action and get its normalized result back inline as already-parsed JSON. Actions are vetted server-side implementations that stay fixed as providers evolve — **use the pre-built action whenever one below covers the operation.** Only the names listed below exist: never invent an action name (an unknown name fails at runtime after a full round trip).
+- **`action(name, input)`** — synchronously trigger a pre-built Nango Action and get its normalized result back inline as already-parsed JSON. Actions are vetted server-side implementations that stay fixed as providers evolve — **use the pre-built action whenever one in that provider's doc covers the operation.** Action signatures exist only in the provider docs; never invent an action name (an unknown name fails at runtime after a full round trip). Do not call `action()` for a provider before reading `.claude/skills/assembly-integrations/providers/<slug>.md`.
 - **`proxy(opts)`** plus verb sugar **`get` / `post` / `put` / `patch` / `delete`(opts)** — relay an arbitrary provider HTTP call, for everything an action doesn't cover. `opts` = `{ endpoint, method?, data?, params?, headers? }`. Each returns the **raw `Response`** (the provider's status/headers/body, relayed transparently) — read it with `await res.json()` / `await res.text()`.
 - **`status()`** — read the workspace's stored connection state (`{ provider, connected, status }`) without touching the provider. See "Checking whether a provider is connected" below.
 
-### Pre-built actions
-
-<!-- ASSEMBLY_ACTIONS -->
-
 ### Resource inputs
 
-Some action inputs are flagged above as **resource inputs**: the value is the ID of something that lives in the provider (a channel, a spreadsheet, a list), and users do not know these IDs. **Never collect a resource input with a free-text ID field.** Use the foundation `ResourcePicker` component if your foundation provides one; otherwise build the same pattern yourself: a select/combobox whose options come from your own API route calling the annotated resolver action, rendering each item's label field and storing its id field **verbatim** as the input value. Apply any note on the annotation (a required filter, a resolver parameter, a multi-select shape) in the fetch. When an annotation says a resource input has no connectable resolver, fall back to a clearly labeled, validated field (e.g. paste the resource's URL and extract the ID from it) — still never a bare "enter the ID" box.
-
-### Example: post a message to Slack
-
-```typescript
-// app/api/slack/post/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration, slackPostMessage } from '@assembly-js/app-foundation/server';
-
-export async function POST(request: NextRequest) {
-  const { channel, text } = await request.json();
-  const slack = await getIntegration('slack');
-  const result = await slackPostMessage(slack, { channel, text });
-  if (!result.ok) {
-    // result.error is Slack's code — 'not_in_channel' means the bot must be
-    // invited to the channel in Slack; 'channel_not_found' means a bad name.
-    return NextResponse.json({ error: result.error }, { status: 502 });
-  }
-  return NextResponse.json(result);
-}
-```
-
-### Example: read a channel's recent messages (action)
-
-```typescript
-// app/api/slack/history/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import { getIntegration } from '@assembly-js/app-foundation/server';
-
-export async function GET(request: NextRequest) {
-  const channelId = request.nextUrl.searchParams.get('channelId') ?? '';
-  const slack = await getIntegration('slack');
-  const history = await slack.action('get-conversation-history', {
-    channel_id: channelId,
-    limit: 10,
-  });
-  return NextResponse.json(history);
-}
-```
-
-For an operation no action covers, relay the provider call through the proxy verbs — e.g.
-`slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })` returns the raw
-provider `Response`.
+Some action inputs are flagged in the provider docs as **resource inputs**: the value is the ID of something that lives in the provider (a channel, a spreadsheet, a list), and users do not know these IDs. **Never collect a resource input with a free-text ID field.** Use the foundation `ResourcePicker` component if your foundation provides one; otherwise build the same pattern yourself: a select/combobox whose options come from your own API route calling the annotated resolver action, rendering each item's label field and storing its id field **verbatim** as the input value. Apply any note on the annotation (a required filter, a resolver parameter, a multi-select shape) in the fetch. When an annotation says a resource input has no connectable resolver, fall back to a clearly labeled, validated field (e.g. paste the resource's URL and extract the ID from it) — still never a bare "enter the ID" box.
 
 ## Letting the user pick a provider resource — ResourcePicker + resolveResource
 
 When the UI needs the user to choose a provider-side resource (a Slack channel, a Drive folder, a spreadsheet, an Airtable base), do NOT hand-roll the combobox plumbing — the foundation ships both halves:
 
-- **`resolveResource(provider, resolverAction, { query?, cursor?, fields, queryInput?, cursorInput?, input? })`** from `@assembly-js/app-foundation/server` — server-side. Runs the resolver action and normalizes the provider's shape to `{ id, label }` options plus `nextCursor`. It returns a serializable `ResourcePage` — broker failures come back as `{ ok: false, error: { code, provider } }` instead of throwing, so the result survives a Server Action boundary (a thrown error is redacted in production). `fields` maps the action's result shape (dot paths allowed) — read it off the action's catalog signature above. Pass `queryInput` only when the action has a server-side search input; otherwise each page is filtered by label locally.
+- **`resolveResource(provider, resolverAction, { query?, cursor?, fields, queryInput?, cursorInput?, input? })`** from `@assembly-js/app-foundation/server` — server-side. Runs the resolver action and normalizes the provider's shape to `{ id, label }` options plus `nextCursor`. It returns a serializable `ResourcePage` — broker failures come back as `{ ok: false, error: { code, provider } }` instead of throwing, so the result survives a Server Action boundary (a thrown error is redacted in production). `fields` maps the action's result shape (dot paths allowed) — read it off the action's catalog signature in that provider's doc. Pass `queryInput` only when the action has a server-side search input; otherwise each page is filtered by label locally.
 - **`<ResourcePicker>`** from `@/app/components/resource-picker` — client-side searchable combobox with debounced search, cursor pagination ("Load more"), loading/empty states, and connector-error surfaces (`needs_reauth` renders a reconnect hint instead of an empty list). Store `value.id`, render `value.label`.
 
 ```typescript
@@ -137,20 +91,6 @@ const [channel, setChannel] = useState<ResourceOption | null>(null);
 <ResourcePicker fetchPage={searchChannels} value={channel} onValueChange={setChannel} placeholder="Search channels…" />
 ```
 
-## Slack specifics
-
-- **Post messages with `slackPostMessage` from `@assembly-js/app-foundation/server` — never hand-roll `chat.postMessage`.** It resolves a `#name` to the channel ID, posts, and on `not_in_channel` joins the channel and retries once. Slack-level failures come back as `{ ok: false, error }`; on `not_in_channel` render "invite the bot to #channel in Slack" (private channels cannot be self-joined).
-- **Resolve channel names with `slackFindChannelId` from `@assembly-js/app-foundation/server` for every other per-channel call — never hand-roll the lookup.** It handles cursor pagination (a single `conversations.list` call misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID for every follow-up call; most Slack methods reject a `#name` with `invalid_arguments`.
-- **Writes need membership, not just visibility.** `slackPostMessage` handles this for posting. For any other write (reactions, uploads), a `not_in_channel` error means join first: the `join-channel` action with the channel ID, then retry once. Private channels cannot be self-joined — they fail `method_not_supported_for_channel_type`, so tell the user to invite the bot instead of retrying.
-- **Scopes:** `chat:write.public` lets posting reach any public channel without joining it, so only the other writes need `join-channel`. Add `groups:read` if the app must find private channels.
-
-```typescript
-import { getIntegration, slackFindChannelId } from '@assembly-js/app-foundation/server';
-
-const slack = await getIntegration('slack');
-const channelId = await slackFindChannelId(slack, 'general');
-```
-
 ## Error handling
 
 A connector call throws a **`ConnectorError`** (with `.code`, `.provider`, `.status`) when the broker returns a structured failure. Catch it and render an empty/error state instead of crashing the page. The codes:
@@ -203,3 +143,4 @@ const { connected, status } = await slack.status();
 - Do NOT install `@nangohq/node` or reference any `NANGO_*` environment variables — there are none; the broker is the only path to a connected provider.
 - Do NOT use `requiredIntegrations` for a provider outside the supported whitelist — fall back to `requiredSecrets`.
 - Do NOT infer "not connected" from a call failing (a non-2xx, a thrown error, a 404 from a wrong endpoint). A connection you can see in **Manage connections** stays connected regardless of individual call failures. Use `isConnected(provider)` / `status()` (above) for connectivity checks — never a live provider call.
+- Do NOT call `action()` for a provider, or invent an action name or input shape, without reading `.claude/skills/assembly-integrations/providers/<slug>.md` first.

package/skills/assembly-integrations/providers/airtable.md

@@ -0,0 +1,24 @@
+# Airtable
+
+`list-records` JSON cells are machine values: a linked-record field is an array of `rec…` IDs (not the primary-field label), and a percent is a 0–1 fraction (`0.42`, not `42%`). Currency, date, dateTime, and duration are similarly unformatted. Never render a field value without reading that field's `type` and `options` from `get-base-schema`.
+
+- **Display (prefer the helper):** `getAirtableTableSchema` + `formatAirtableRecords` from `@assembly-js/app-foundation/server` return raw + display per field so sorts and writes keep machine values. They format percent / currency / number / date / dateTime / duration from field options, and resolve linked IDs to the linked table's primary field. A missing linked record stays the raw ID. Server-side only — pass the `getIntegration` client.
+- **Computed-field errors:** formula/lookup/rollup cells can come back as an error-state object (`{state:"error",errorType:"emptyDependency"}`) or a numeric special value (`{specialValue:"NaN"}`) instead of a real value — never render a cell object raw. The helper guards this (`display` becomes `—`, `raw` stays untouched); code that skips the helper must guard for it itself.
+- **Display without the helper, or a display-only table:** pass `cellFormat: "string"` on `list-records` to get Airtable's formatted strings. Trade-off: values come back as display strings, so you lose machine-readable raw numbers/IDs for sorting and writes — don't use this when you also edit or sort those cells. Otherwise do the schema path yourself: format percent as `(value * 100)` + `%` (precision from field options); for each `multipleRecordLinks` field, `list-records` on `options.linkedTableId` with `filterByFormula` `OR(RECORD_ID()='rec…',…)` (chunk the OR — one page can collect more IDs than a safe formula length), `fields` set to only the linked table's primary field, and substitute labels. Failures keep the raw ID.
+- **Pagination:** `list-bases` takes `cursor` and returns `nextOffset`. `list-records` takes `offset` and returns `offset`. Passing the wrong key silently drops the next page.
+- **`fields` is overloaded:** on `list-records` it is an array of field names to return; on `create-record` / `update-record` it is a name-or-id-keyed map of values to write. An array on a write, or a map on a read, is rejected.
+- Resolve `baseId` with `list-bases` and table/field names with `get-base-schema` before writes. `tableIdOrName` accepts either; schema field ids survive a user renaming the column.
+
+```typescript
+import { getIntegration, getAirtableTableSchema, formatAirtableRecords } from '@assembly-js/app-foundation/server';
+
+const airtable = await getIntegration('airtable');
+const { records } = await airtable.action('list-records', { baseId, tableIdOrName });
+const table = await getAirtableTableSchema(airtable, baseId, tableIdOrName);
+if (!table.ok) return;
+const rows = await formatAirtableRecords(records, table.schema, { client: airtable, baseId });
+// rows[i].fields.Engagement.raw === 0.42
+// rows[i].fields.Engagement.display === "42%"
+```
+
+<!-- ASSEMBLY_ACTIONS:airtable -->

package/skills/assembly-integrations/providers/calendly.md

@@ -0,0 +1,7 @@
+# Calendly
+
+Resources are addressed by full URI in results, but inputs take a bare UUID. Chaining `list-scheduled-events` into `list-event-invitees` means splitting the last path segment off the event's `uri` — no result field carries the bare uuid, so no picker can store it verbatim.
+
+The connection's own user is resolved internally; no user parameter is required.
+
+<!-- ASSEMBLY_ACTIONS:calendly -->

package/skills/assembly-integrations/providers/clickup.md

@@ -0,0 +1,11 @@
+# ClickUp
+
+Hierarchy is workspace → space → folder → list → task. `list-teams` is the only action that takes no id; every other level needs its parent. ClickUp calls a workspace a team.
+
+Walk down: `list-teams` → `list-spaces` (`team_id`) → `list-folders` (`space_id`) → `list-lists` (exactly one of `folder_id` or `space_id`; `space_id` returns lists sitting outside any folder) → `list-tasks` (`list_id`).
+
+- **create-task vs update-task:** the same task comes back with nested `status` / `priority` / `assignee` objects from one and flattened scalars from the other. `assignees` is a flat array of numeric user ids on create, and `{ add, rem }` on update.
+- **User ids:** `list-users` returns string ids; the task actions want numbers. Cast before writing — a picker that stores the string verbatim is rejected.
+- Dates are unix milliseconds. Priority is 1 (urgent) through 4 (low).
+
+<!-- ASSEMBLY_ACTIONS:clickup -->

package/skills/assembly-integrations/providers/dropbox.md

@@ -0,0 +1,7 @@
+# Dropbox
+
+Files are addressed by path, not id. `list-folder` entries carry `path_display` for follow-up calls; `download-file` also accepts an `id:...` identifier.
+
+`list-folder` reports only `.tag` / `id` / `name` / `path_lower` / `path_display` per entry. The `rev` that `upload-file`'s `update` mode requires comes only from `get-file-or-folder-metadata` (and only for files). Mode `add` creates, `overwrite` replaces, `update` needs the current rev.
+
+<!-- ASSEMBLY_ACTIONS:dropbox -->

package/skills/assembly-integrations/providers/gmail.md

@@ -0,0 +1,7 @@
+# Gmail
+
+Send-only: `gmail.send` is Google's one sensitive-tier Gmail scope; every read/draft scope is restricted (CASA audit), so those actions are unvendored. Do not invent a list or read action, and do not declare a read scope.
+
+`send-message` takes `raw`: the complete RFC 2822 MIME message, base64url-encoded. `threadId` makes it a reply; there is no in-catalog resolver for threads, so collect it from a previous send result, not a picker.
+
+<!-- ASSEMBLY_ACTIONS:gmail -->

package/skills/assembly-integrations/providers/google-calendar.md

@@ -0,0 +1,7 @@
+# Google Calendar
+
+`calendarId` defaults to `primary` on `list-events`. `create-event` requires `calendarId` plus `start` / `end` as `{ dateTime, timeZone? }` in RFC3339.
+
+`list-events` paginates with `cursor` in and `nextPageToken` out. `update-event` is a patch — only supplied fields change.
+
+<!-- ASSEMBLY_ACTIONS:google-calendar -->

package/skills/assembly-integrations/providers/google-drive.md

@@ -0,0 +1,7 @@
+# Google Drive
+
+`folderId` / `parentId` default to the drive root. `find-file` `query` takes Drive search syntax (e.g. `name contains 'report'` or a MIME-type filter). `upload-document` accepts plain text or base64 content up to 5 MB.
+
+`list-files-non-unified` lists only the immediate children of a folder.
+
+<!-- ASSEMBLY_ACTIONS:google-drive -->

package/skills/assembly-integrations/providers/google-sheet.md

@@ -0,0 +1,9 @@
+# Google Sheets
+
+Sheets has no in-provider listing. Spreadsheets live in Drive.
+
+When `google-drive` is on the supported-provider list, declare it too and resolve `spreadsheetId` via Drive `find-file` with query `mimeType='application/vnd.google-apps.spreadsheet'` (id field `id`, label `name`). When Drive is not connectable, collect the spreadsheet URL and extract the id — never a bare "enter the ID" box.
+
+Ranges are A1 notation; `values` is a 2D array of rows. `get-values` reads, `append-values-to-spreadsheet` appends to the table found in the range, `update-values` overwrites an exact range.
+
+<!-- ASSEMBLY_ACTIONS:google-sheet -->

package/skills/assembly-integrations/providers/hubspot.md

@@ -0,0 +1,10 @@
+# HubSpot
+
+Shapes are inconsistent across objects. Read each signature below — do not generalise casing, id-param names, or list result keys from a neighbouring entry.
+
+- **List result keys:** `list-contacts` and `list-deals` return `contacts` / `deals`; `list-companies` returns `items`.
+- **Id params:** `update-contact` takes `contactId`, `update-deal` takes `dealId`, `update-company` takes plain `id`.
+- **Name casing:** `create-contact` uses `firstname` / `lastname`; `update-contact` uses `firstName` / `lastName`. `create-deal` uses `dealName`; `update-deal` uses `dealname`.
+- **Pipelines:** `fetch-pipelines` resolves the ids `create-deal` / `update-deal` need (`objectType` defaults to `deals`). `dealstage` is nested under each pipeline — no flat picker metadata exists, so resolve it from the pipeline payload rather than inventing a stage resolver.
+
+<!-- ASSEMBLY_ACTIONS:hubspot -->

package/skills/assembly-integrations/providers/quickbooks.md

@@ -0,0 +1,9 @@
+# QuickBooks
+
+Writes use optimistic locking: updates need the record's current `SyncToken`. `get-invoice` returns `syncToken`; `get-customer`, `list-customers`, and `create-customer` omit it, so `update-customer` cannot be chained from this action set alone — read the current token through the proxy before updating.
+
+Casing is mixed: `create-invoice` takes camelCase; every other write takes QuickBooks' PascalCase. List result keys are `items` except `list-payments` (`payments`). Read each signature below.
+
+`CustomerRef` / `itemRef` / `LinkedTxn` shapes are in the catalog. Multi-account connections are keyed by `realmId`.
+
+<!-- ASSEMBLY_ACTIONS:quickbooks -->

package/skills/assembly-integrations/providers/slack.md

@@ -0,0 +1,27 @@
+# Slack
+
+Writes need membership, not just visibility. `send-message` reaches public channels without joining; other writes fail `not_in_channel` until the bot joins.
+
+- **Post with `slackPostMessage` from `@assembly-js/app-foundation/server` — never hand-roll `chat.postMessage`.** It resolves a `#name` to the channel ID, posts, and on `not_in_channel` joins the channel and retries once. Slack-level failures come back as `{ ok: false, error }`; on `not_in_channel` render "invite the bot to #channel in Slack" (private channels cannot be self-joined).
+- **Resolve channel names with `slackFindChannelId` from `@assembly-js/app-foundation/server` for every other per-channel call.** It handles cursor pagination (a single `conversations.list` misses channels in large workspaces), name normalization, scope fallback, rate limits, and caching. Use the returned ID; most Slack methods reject a `#name` with `invalid_arguments`.
+- **Other writes (reactions, uploads):** on `not_in_channel`, call `join-channel` with the channel ID, then retry once. Private channels fail `method_not_supported_for_channel_type` — tell the user to invite the bot instead of retrying.
+- **Scopes:** `chat:write.public` lets posting reach any public channel without joining, so only the other writes need `join-channel`. Add `groups:read` if the app must find private channels.
+
+```typescript
+import { getIntegration, slackFindChannelId, slackPostMessage } from '@assembly-js/app-foundation/server';
+
+const slack = await getIntegration('slack');
+const channelId = await slackFindChannelId(slack, 'general');
+const posted = await slackPostMessage(slack, { channel: '#general', text: 'Hello' });
+```
+
+```typescript
+const history = await slack.action('get-conversation-history', {
+  channel_id: channelId,
+  limit: 10,
+});
+```
+
+For an operation no action covers, relay through the proxy — e.g. `slack.post({ endpoint: '/chat.update', data: { channel: channelId, ts, text } })`.
+
+<!-- ASSEMBLY_ACTIONS:slack -->

package/skills/assembly-integrations/providers/stripe.md

@@ -0,0 +1,7 @@
+# Stripe
+
+List cursors are the id of the last item on the previous page (Stripe's `starting_after`), not an opaque token. Passing a `next_cursor` from another provider, or anything that is not an item id, skips or repeats pages.
+
+`get-customer` returns the customer flat, not wrapped. Email filters on `list-customers` are case-sensitive exact matches.
+
+<!-- ASSEMBLY_ACTIONS:stripe -->

package/skills/assembly-integrations/providers/twilio.md

@@ -0,0 +1,8 @@
+# Twilio
+
+Most actions resolve the Account SID from the connection — except `create-call`, which requires `account_sid` as input. Each `list-incoming-phone-numbers` item carries `account_sid`; read it from there rather than inventing a sid source.
+
+- **`list-incoming-phone-numbers` is the camelCase outlier** (`friendlyName`, `phoneNumber`, `pageSize`). Every other Twilio action is snake_case.
+- `send-sms` requires exactly one of `from` (a number the account owns — resolve via `list-incoming-phone-numbers`) or `messaging_service_sid`.
+
+<!-- ASSEMBLY_ACTIONS:twilio -->

package/skills/assembly-integrations/providers/xero.md

@@ -0,0 +1,10 @@
+# Xero
+
+Every call is tenant-scoped. The templates resolve the organisation from `connection_config.tenant_id` (snake_case on the wire), then `metadata.tenantId`, then a live `/connections` lookup that errors when the token spans several organisations. Use `list-tenants` to get the `tenantId` that scopes the rest.
+
+Shapes and pagination disagree across actions — read each signature below.
+
+- **Pagination:** `list-contacts` / `list-invoices` use page numbers (`page` / `next_page`). `list-accounts` uses a cursor (`cursor` / `next_cursor`). `list-payments` returns `Pagination` / `NextPage`.
+- **Casing:** writes are mostly PascalCase (`Name`, `ContactID`, `InvoiceID`); `create-invoice` / `create-payment` take snake_case; `get-contact` returns camelCase; `list-payments` output keys are PascalCase.
+
+<!-- ASSEMBLY_ACTIONS:xero -->