@softr/sdk 0.0.41 → 0.0.43

package/dist/cli.js

@@ -2,15 +2,19 @@
 import { version } from "./package.js";
 import { fetchSoftrEnvInput, metadataSourceFromEnv } from "./codegen/fetch-metadata.js";
 import { renderSoftrEnv } from "./codegen/softr-env.js";
+import { writeDatasourceDocs } from "./codegen/write-datasource-docs.js";
 import { writeFileSync } from "node:fs";
 import path from "node:path";
 
 //#region src/cli.ts
 const OUTPUT = "softr-env.d.ts";
+const DOCS_DIR = "docs/datasources";
 async function generate() {
 	const input = await fetchSoftrEnvInput(metadataSourceFromEnv());
 	writeFileSync(path.resolve(process.cwd(), OUTPUT), renderSoftrEnv(input, version), "utf8");
 	console.log(`[softr] wrote ${OUTPUT} (${input.datasources.length} datasources)`);
+	writeDatasourceDocs(input.datasources, path.resolve(process.cwd(), DOCS_DIR));
+	console.log(`[softr] wrote ${DOCS_DIR} (${input.datasources.length} datasources)`);
 }
 const [command] = process.argv.slice(2);
 if (command === "generate") await generate();

package/dist/codegen/datasource-docs.js

@@ -0,0 +1,318 @@
+import { assert, requireDefined } from "../assertions.js";
+import { choiceEntries, fieldTypeLiteral, isWritable, option, readExample, resolvedShape, scalarExample, underlyingType } from "./datasource-types.js";
+
+//#region src/codegen/datasource-docs.ts
+const DOC_NOTE = "> This document is generated automatically when a change is made in the datasource.";
+const INDEX_NOTE = "> These documents are generated automatically when a change is made in a datasource.";
+function renderDatasourceDoc(datasource, context) {
+	return [
+		`# ${datasourceLabel(datasource)}`,
+		"",
+		...summary(datasource, context),
+		"",
+		DOC_NOTE,
+		"",
+		"## Field reference",
+		"",
+		...orderedFields(datasource).flatMap((field) => [...renderField(field, datasource, context), ""]),
+		...renderExamples(datasource, context.datasources)
+	].join("\n");
+}
+/** Two trailing spaces are a markdown hard break, which keeps the block one paragraph. */
+function summary(datasource, context) {
+	const lines = [`Datasource ID: ${datasource.id}`];
+	const related = relatedLinks(datasource, context);
+	if (related.length > 0) {
+		const label = related.length === 1 ? "datasource" : "datasources";
+		lines.push(`Related ${label}: ${related.join(", ")}`);
+	}
+	return lines.map((line, index) => index === lines.length - 1 ? line : `${line}  `);
+}
+function relatedLinks(datasource, context) {
+	const seen = /* @__PURE__ */ new Set();
+	const links = [];
+	for (const field of datasource.fields) {
+		const linkedId = option(field.options, "linkedTableId");
+		if (typeof linkedId !== "string" || seen.has(linkedId)) continue;
+		seen.add(linkedId);
+		const linked = context.datasources.get(linkedId);
+		if (linked === void 0 || linked.id === datasource.id) continue;
+		links.push(docLink(linked, context));
+	}
+	return links;
+}
+function docLink(datasource, context) {
+	const file = requireDefined(context.fileNames.get(datasource.id), `No doc file name for datasource ${datasource.id}`);
+	return `[${datasourceLabel(datasource)}](./${file})`;
+}
+function renderDatasourceIndex(datasources, context) {
+	const heading = [
+		"# Datasources",
+		"",
+		INDEX_NOTE,
+		""
+	];
+	if (datasources.length === 0) return [
+		...heading,
+		"This app has no registered datasources.",
+		""
+	].join("\n");
+	return [
+		...heading,
+		"Datasources available in this app:",
+		"",
+		...datasources.map((datasource) => {
+			const file = requireDefined(context.fileNames.get(datasource.id), `No doc file name for datasource ${datasource.id}`);
+			return `- ${datasourceLabel(datasource)} (${datasource.id}), [${file}](./${file})`;
+		}),
+		""
+	].join("\n");
+}
+function orderedFields(datasource) {
+	const primary = datasource.fields.filter((field) => field.id === datasource.primaryFieldId);
+	const rest = datasource.fields.filter((field) => field.id !== datasource.primaryFieldId);
+	return [...primary, ...rest];
+}
+function renderField(field, datasource, context) {
+	return [
+		displayName(field.name),
+		"",
+		...detail(field, datasource, context)
+	];
+}
+/** The options that change what a value means or what a valid one looks like, and no others. */
+const DETAILED_OPTIONS = [
+	{
+		key: "isoCode",
+		label: "Currency"
+	},
+	{
+		key: "precision",
+		label: "Precision"
+	},
+	{
+		key: "min",
+		label: "Min"
+	},
+	{
+		key: "max",
+		label: "Max"
+	},
+	{
+		key: "format",
+		label: "Format"
+	}
+];
+function detail(field, datasource, context) {
+	const lines = [`- ID: ${field.id}`, `- Type: ${fieldTypeLiteral(field).slice(1, -1)}`];
+	if (field.id === datasource.primaryFieldId) lines.push("- Primary field");
+	const chain = underlyingType(field);
+	if (chain.includes("->")) lines.push(`- Resolves: ${chain}`);
+	lines.push(...optionLines(field));
+	lines.push(...choiceLines(field));
+	lines.push(...linkLine(field, context));
+	const applied = flags(field);
+	if (applied.length > 0) lines.push(`- Flags: ${applied.join(", ")}`);
+	if (field.defaultValue !== null && field.defaultValue !== void 0) lines.push(`- Default: ${code(JSON.stringify(field.defaultValue))}`);
+	lines.push(...formulaLines(field));
+	lines.push(`- Example: ${code(readValueExample(field, context.datasources))}`);
+	return lines;
+}
+function flags(field) {
+	const applied = [];
+	if (field.required) applied.push("required");
+	if (!isWritable(field)) applied.push("readonly");
+	if (field.createOnly) applied.push("createOnly");
+	if (field.aiOnly === true) applied.push("aiOnly");
+	return applied;
+}
+function optionLines(field) {
+	const { options } = resolvedShape(field);
+	return DETAILED_OPTIONS.flatMap(({ key, label }) => {
+		const value = option(options, key);
+		if (value === null || value === void 0) return [];
+		assert(typeof value !== "object", `Option ${key} on field ${field.id} is not a scalar`);
+		return [`- ${label}: ${String(value)}`];
+	});
+}
+function linkLine(field, context) {
+	const linkedId = option(field.options, "linkedTableId");
+	if (typeof linkedId !== "string") return [];
+	const linked = context.datasources.get(linkedId);
+	if (linked === void 0) return [`- Links to: ${linkedId}, not registered`];
+	return [`- Links to: ${docLink(linked, context)} (${linked.id})`];
+}
+function choiceLines(field) {
+	const choices = choiceEntries(resolvedShape(field).options);
+	if (choices === null) return [];
+	return ["- Choices:", ...choices.map(({ id, label }) => `  - ${id} ${displayName(label)}`)];
+}
+function formulaLines(field) {
+	const formula = option(field.options, "formula");
+	if (typeof formula !== "string" || formula.includes("```")) return [];
+	return [
+		"- Formula:",
+		"  ```",
+		...formula.split("\n").map((line) => `  ${line}`),
+		"  ```"
+	];
+}
+function exampleFieldKeys(datasource) {
+	const keys = /* @__PURE__ */ new Map();
+	const used = /* @__PURE__ */ new Set();
+	for (const field of datasource.fields) {
+		const base = camelCase(field.name) || camelCase(field.id) || "field";
+		let key = base;
+		let suffix = 1;
+		while (used.has(key)) {
+			suffix += 1;
+			key = `${base}${suffix}`;
+		}
+		used.add(key);
+		keys.set(field.id, key);
+	}
+	return keys;
+}
+function renderExamples(datasource, datasources) {
+	const keys = exampleFieldKeys(datasource);
+	const keyOf = (field) => requireDefined(keys.get(field.id), `No example key for field ${field.id} on datasource ${datasource.id}`);
+	const queryId = camelCase(datasource.name) || camelCase(datasource.id);
+	assert(queryId !== "", `Datasource ${datasource.id} has no usable name`);
+	const name = pascalCase(datasource.name) || pascalCase(datasource.id);
+	const sampled = exampleFields(datasource);
+	const read = [
+		"## Read shape",
+		"",
+		"```ts",
+		"import { createServerFn } from '@tanstack/react-start'",
+		"import { defineQuery } from '@softr/sdk'",
+		"import { ds } from '@softr/sdk/server'",
+		"",
+		`const ${queryId} = defineQuery({`,
+		`  id: ${quoted(queryId)},`,
+		`  datasourceId: ${quoted(datasource.id)},`,
+		"  fields: {",
+		...sampled.map((field) => `    ${keyOf(field)}: ${quoted(field.id)}, // ${fieldTypeLiteral(field).slice(1, -1)}`),
+		"  },",
+		"  permissions: { userGroup: 'ALL_USERS' },",
+		"})",
+		"",
+		`const list${name} = createServerFn().handler(async () => {`,
+		`  return await ds.list(${queryId})`,
+		"})",
+		"```",
+		"",
+		"```ts",
+		"const fields = {",
+		...sampled.map((field) => `  ${keyOf(field)}: ${readValueExample(field, datasources)},`),
+		"}",
+		"```"
+	];
+	const writable = sampled.filter(isWritableExample);
+	if (writable.length === 0) return [...read, ""];
+	const mutationId = `create${name}`;
+	const write = [
+		"## Write shape",
+		"",
+		"```ts",
+		"import { createServerFn } from '@tanstack/react-start'",
+		"import { defineMutation } from '@softr/sdk'",
+		"import { ds } from '@softr/sdk/server'",
+		"",
+		`const ${mutationId} = defineMutation({`,
+		`  id: ${quoted(mutationId)},`,
+		`  datasourceId: ${quoted(datasource.id)},`,
+		"  operation: 'create',",
+		"  fields: {",
+		...writable.map((field) => `    ${keyOf(field)}: ${quoted(field.id)},`),
+		"  },",
+		"  permissions: { userGroup: 'LOGGED_IN_USERS' },",
+		"})",
+		"",
+		`const add${name} = createServerFn({ method: 'POST' }).handler(async () =>`,
+		`  ds.create(${mutationId}, {`,
+		"    data: {",
+		...writable.map((field) => `      ${keyOf(field)}: ${writeValueExample(field)},`),
+		"    },",
+		"  }),",
+		")",
+		"```",
+		""
+	];
+	return [
+		...read,
+		"",
+		...write
+	];
+}
+/**
+* The first field of every type the datasource has, because two fields of one type show one
+* shape. `SELECT` and `SELECT[]` are two types, so both appear, and `orderedFields` puts the
+* primary field first, so it is always the first of its own type.
+*/
+function exampleFields(datasource) {
+	const types = /* @__PURE__ */ new Set();
+	return orderedFields(datasource).filter((field) => {
+		const type = fieldTypeLiteral(field);
+		if (types.has(type)) return false;
+		types.add(type);
+		return true;
+	});
+}
+function isWritableExample(field) {
+	return isWritable(field) && field.aiOnly !== true;
+}
+function readValueExample(field, datasources) {
+	const choice = firstChoice(field);
+	if (choice !== null) return exampleLiteral(field, `{ id: ${quoted(choice.id)}, label: ${quoted(choice.label)} }`);
+	return exampleLiteral(field, readExample(field, datasources));
+}
+function writeValueExample(field) {
+	const choice = firstChoice(field);
+	if (choice !== null) return exampleLiteral(field, `{ id: ${quoted(choice.id)} }`);
+	return exampleLiteral(field, scalarExample(field));
+}
+function datasourceLabel(datasource) {
+	return displayName(datasource.name) || datasource.id;
+}
+/** A wider delimiter, because a value carrying a label can carry a backtick of its own. */
+function code(value) {
+	return value.includes("`") ? `\`\` ${value} \`\`` : `\`${value}\``;
+}
+/** Names and labels arrive verbatim from the API, where a line break forges a row. */
+function displayName(name) {
+	return name.replace(/\s+/g, " ").trim();
+}
+function quoted(value) {
+	return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'").replace(/\n/g, "\\n").replace(/\r/g, "\\r")}'`;
+}
+function exampleLiteral(field, scalar) {
+	if (field.allowMultipleEntries) return scalar === null ? "[]" : `[${scalar}]`;
+	return scalar ?? "null";
+}
+/**
+* A choice id the datasource declares, which is what the generated read type accepts. Read from
+* the resolved shape, because the read type resolves a computed field the same way.
+*/
+function firstChoice(field) {
+	const shape = resolvedShape(field);
+	if (shape.type !== "SELECT") return null;
+	const choices = choiceEntries(shape.options);
+	return choices === null ? null : choices[0];
+}
+function camelCase(value) {
+	const parts = words(value);
+	if (parts.length === 0) return "";
+	const joined = parts.map((word, index) => index === 0 ? word[0].toLowerCase() + word.slice(1) : word[0].toUpperCase() + word.slice(1)).join("");
+	return /^[0-9]/.test(joined) ? `f${joined}` : joined;
+}
+function pascalCase(value) {
+	const joined = words(value).map((word) => word[0].toUpperCase() + word.slice(1)).join("");
+	return /^[0-9]/.test(joined) ? `F${joined}` : joined;
+}
+function words(value) {
+	return value.split(/[^A-Za-z0-9]+/).filter((word) => word.length > 0);
+}
+
+//#endregion
+export { renderDatasourceDoc, renderDatasourceIndex };

package/dist/codegen/datasource-types.js

@@ -299,7 +299,7 @@ function fieldDoc(field, datasource, context, side) {
 	const lines = [`Name: ${field.name}`, `Underlying type: ${underlyingType(field)}`];
 	const tags = [];
 	if (field.defaultValue !== null && field.defaultValue !== void 0) tags.push(`@default ${JSON.stringify(field.defaultValue)}`);
-	const scalar = read ? readExample(field) : scalarExample(field);
+	const scalar = read ? readExample(field, context.datasources) : scalarExample(field);
 	if (scalar !== null) tags.push(`@example ${field.allowMultipleEntries ? `[${scalar}]` : scalar}`);
 	tags.push(...shapeTags(field));
 	if (field.id === datasource.primaryFieldId) tags.push("@primaryField");
@@ -373,21 +373,38 @@ function formulaTag(field) {
 /** Stands in for any id in an example. The real ones are in the member type below it. */
 const BLANK_ID = "00000000-0000-0000-0000-000000000000";
 /** The read counterpart of {@link scalarExample}, wherever the API returns a different shape. */
-function readExample(shape) {
+function readExample(shape, datasources) {
 	switch (shape.type) {
 		case "SELECT": {
 			const choices = choiceEntries(shape.options);
 			return `{ id: '${BLANK_ID}', label: '${choices === null ? "text" : choices[0].label}' }`;
 		}
-		case "LINKED_RECORD": return `{ id: '${BLANK_ID}', label: 'text' }`;
+		case "LINKED_RECORD": return `{ id: '${BLANK_ID}', label: ${linkedLabelExample(shape.options, datasources)} }`;
 		case "ATTACHMENT": return `{ id: '${BLANK_ID}', filename: 'file.pdf', type: 'application/pdf', url: 'https://example.com/file.pdf', expiresAt: '2026-03-14T09:30:00.000Z' }`;
 		case "LOCATION": return "'text'";
 		case "FORMULA":
 		case "LOOKUP":
-		case "ROLLUP": return readExample(returnedShape(shape));
+		case "ROLLUP": return readExample(returnedShape(shape), datasources);
 		default: return scalarExample(shape);
 	}
 }
+/**
+* The label a read carries, resolved the way {@link linkedRecord} resolves its type: the linked
+* table's primary field. `null` wherever that resolution fails, which says nothing about a table
+* this app cannot see and inhabits every `LinkedRecord<T>` label.
+*/
+function linkedLabelExample(options, datasources) {
+	const linkedTableId = option(options, "linkedTableId");
+	if (typeof linkedTableId !== "string") return "null";
+	const linked = datasources.get(linkedTableId);
+	const primary = linked?.fields.find((field) => field.id === linked.primaryFieldId);
+	if (linked === void 0 || primary === void 0) return "null";
+	const rest = new Map(datasources);
+	rest.delete(linked.id);
+	const scalar = readExample(primary, rest);
+	if (scalar === null) return "null";
+	return primary.allowMultipleEntries ? `[${scalar}]` : scalar;
+}
 /** A literal showing the shape a write takes, or `null` where the shape is not settled. */
 function scalarExample(shape) {
 	switch (shape.type) {
@@ -468,4 +485,4 @@ function indent(block) {
 }
 
 //#endregion
-export { renderDatasourceTypes };
+export { choiceEntries, fieldTypeLiteral, isWritable, option, readExample, renderDatasourceTypes, resolvedShape, scalarExample, underlyingType };

package/dist/codegen/doc-file-names.js

@@ -0,0 +1,31 @@
+import { panic } from "../assertions.js";
+
+//#region src/codegen/doc-file-names.ts
+function docFileNames(datasources) {
+	const bases = /* @__PURE__ */ new Map();
+	const seen = /* @__PURE__ */ new Map();
+	for (const datasource of datasources) {
+		const base = slug(datasource.name) || slug(datasource.id);
+		if (base === "") panic(`Datasource ${datasource.id} has no usable name`);
+		bases.set(datasource.id, base);
+		const key = base.toLowerCase();
+		seen.set(key, (seen.get(key) ?? 0) + 1);
+	}
+	const names = /* @__PURE__ */ new Map();
+	/** The index the docs route the agent through, which a datasource must not overwrite. */
+	const taken = new Set(["readme"]);
+	for (const [id, base] of bases) {
+		const candidate = seen.get(base.toLowerCase()) === 1 ? base : `${base}-${id}`;
+		let name = candidate;
+		for (let attempt = 2; taken.has(name.toLowerCase()); attempt++) name = `${candidate}-${attempt}`;
+		taken.add(name.toLowerCase());
+		names.set(id, `${name}.md`);
+	}
+	return names;
+}
+function slug(value) {
+	return value.split(/[^A-Za-z0-9]+/).filter((word) => word.length > 0).join("-");
+}
+
+//#endregion
+export { docFileNames };

package/dist/codegen/softr-env.js

@@ -32,8 +32,11 @@ function header(sdkVersion) {
 	return `/**
  * THIS FILE IS AUTO GENERATED, DO NOT EDIT THIS MANUALLY
  *
+ * This file exists for type checking. See docs/datasources/ for field reference
+ * and guide how to use it.
+ *
  * Generated by @softr/sdk@${sdkVersion}
- * This file is regenerated automatically at the end of the turn
+ * This file is regenerated automatically when a change is made to the datasource
  */
 
 export {};`;

package/dist/codegen/write-datasource-docs.js

@@ -0,0 +1,24 @@
+import { requireDefined } from "../assertions.js";
+import { renderDatasourceDoc, renderDatasourceIndex } from "./datasource-docs.js";
+import { docFileNames } from "./doc-file-names.js";
+import { mkdirSync, writeFileSync } from "node:fs";
+import path from "node:path";
+
+//#region src/codegen/write-datasource-docs.ts
+/**
+* Writes the index and one file per datasource, and touches nothing else in
+* `docsDir`: the caller resolves it against `process.cwd()`, which can be any
+* directory a developer ran the bin from.
+*/
+function writeDatasourceDocs(datasources, docsDir) {
+	const context = {
+		datasources: new Map(datasources.map((datasource) => [datasource.id, datasource])),
+		fileNames: docFileNames(datasources)
+	};
+	mkdirSync(docsDir, { recursive: true });
+	writeFileSync(path.join(docsDir, "README.md"), renderDatasourceIndex(datasources, context), "utf8");
+	for (const datasource of datasources) writeFileSync(path.join(docsDir, requireDefined(context.fileNames.get(datasource.id))), renderDatasourceDoc(datasource, context), "utf8");
+}
+
+//#endregion
+export { writeDatasourceDocs };

package/dist/package.js

@@ -1,5 +1,5 @@
 //#region package.json
-var version = "0.0.41";
+var version = "0.0.43";
 
 //#endregion
 export { version };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@softr/sdk",
-  "version": "0.0.41",
+  "version": "0.0.43",
   "type": "module",
   "exports": {
     ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" },

package/skills/softr-sdk/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: core
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 # Softr SDK core

package/skills/softr-sdk/auth/SKILL.md

@@ -16,7 +16,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `auth` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineVisibility`, the hooks and every type come from `@softr/sdk`. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/charts-and-metrics/SKILL.md

@@ -12,7 +12,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/current-user/SKILL.md

@@ -10,7 +10,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `useCurrentUser`, `usePermissions` and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/file-uploads/SKILL.md

@@ -1,15 +1,16 @@
 ---
 name: file-uploads
 description: >-
-  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk does
-  everything — XHR upload with real progress, per-upload cancel, and isUploading to block
-  form submission. No route registration needed; the SDK ships its own server function.
-  For server-side uploads or plain forms, use upload(actionId, file) from @softr/sdk/server.
-  For edit forms pass initialAttachments to pre-load existing attachments.
+  Upload files from a form or edit view: useFileUpload(action) from @softr/sdk
+  does everything — XHR upload with real progress, per-upload cancel, and
+  isUploading to block form submission. No route registration needed; the SDK
+  ships its own server function. For server-side uploads or plain forms, use
+  upload(actionId, file) from @softr/sdk/server. For edit forms pass
+  initialAttachments to pre-load existing attachments.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `upload` lives on `@softr/sdk/server` and runs inside server functions. `useFileUpload` and `FileItem` live on `@softr/sdk` and run in components. `FileAttachment` comes from `@softr/sdk` and can be imported anywhere.

package/skills/softr-sdk/integrations/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `integration` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineIntegration` and every type come from `@softr/sdk` and can be imported anywhere. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -148,6 +148,10 @@ Match the `integrationType` from the attached integrations section to find the b
 | XERO | `https://api.xero.com` |
 | ZOOM | `https://api.zoom.us` |
 
+## When the type is in the table but nothing is attached
+
+The service is not out of reach, it is not connected yet. Load `connect-a-service` and ask the user for it: the answer carries the `integrationId` this skill needs.
+
 ## When the service is not a Softr integration
 
 If the API the user needs is not in the table above, call it directly from a server function using the native `fetch`. The user supplies their own credentials and the call lives entirely in the server function handler.

package/skills/softr-sdk/record-mutations/SKILL.md

@@ -11,7 +11,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineMutation` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/record-queries/SKILL.md

@@ -13,7 +13,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `ds` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler or a server-side route hook — importing it into a component fails the build. `defineQuery` and every type come from `@softr/sdk` and can be imported anywhere. The app is already wired (`src/start.ts`, `src/router.tsx`, `src/routes/__root.tsx`); never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -183,8 +183,7 @@ A read the datasource turns down throws rather than coming back empty, and it th
 
 ## Typing
 
-`softr-env.d.ts`, the generated file at the app root, types records, filters and sorts from every registered datasource. It follows the data on its own: nothing to run, nothing to edit. It checks the ids you wrote rather than handing them to you, so ask the schema for a field id and open the file only when a declaration will not compile.
-
+Queries you write are type safe and a type error is shown when there's a mistake. For an in depth reference on what fields every datasource has check own project's `docs/datasources/` directory.
 
 ## References
 

package/skills/softr-sdk/record-queries/references/field-types.md

@@ -1,6 +1,6 @@
 # Softr field types and what their values look like
 
-The generated `softr-env.d.ts` is the authority for your own tables: it types every field of every registered datasource, choice ids included, with the field's name and constraints in a docstring. This reference is the general mapping behind it, for reading a record's values without opening that file.
+Your own tables are recapped in `docs/datasources/`, one generated file per registered datasource: every field with its name, id, type and constraints, choice ids included. This reference is the general mapping behind those files, for reading a record's values without opening them.
 
 Three rules cover nullability:
 
@@ -39,7 +39,7 @@ ATTACHMENT: {
 }
 
 // Computed fields read as whatever they return
-FORMULA, LOOKUP, ROLLUP: the returned field's shape, resolved in softr-env.d.ts
+FORMULA, LOOKUP, ROLLUP: the returned field's shape, resolved in docs/datasources/
 ```
 
 Every scalar above is `| null` on the record unless the field allows multiple entries, in which case the value is an `Array<...>` of the scalar.

package/skills/softr-sdk/record-queries/references/filters-and-sorting.md

@@ -23,7 +23,7 @@ A `where` callback returns exactly one value. For more than one condition, wrap
 
 ## Operators by field type
 
-The handle for each field carries the operators its declared type supports, taken from the generated `softr-env.d.ts`.
+The handle for each field carries the operators its declared type supports.
 
 ### Text fields
 

package/skills/softr-sdk/routes-and-visibility/SKILL.md

@@ -6,13 +6,13 @@ description: >-
   four ways to enforce a rule (guard, assert, isAuthorized, check). Covers
   per-reason overrides, the redirect and throw strategies, rendering an access
   error with isAccessError, isUnauthenticatedError, isForbiddenError and
-  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that requires a
-  declaration alongside the rules that reject a duplicate, computed or
-  root-level one.
+  isAlreadyAuthenticatedError, guarding a layout, and the lint rule that
+  requires a declaration alongside the rules that reject a duplicate, computed
+  or root-level one.
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `defineVisibility`, the error predicates and every type come from `@softr/sdk` and work anywhere; `ds` and `auth` live on `@softr/sdk/server` and run only inside a `createServerFn` handler. The app is already wired — `src/start.ts` registers `softrAuthMiddleware`, `src/routes/__root.tsx` publishes the visitor as route context — never add a second registration. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.

package/skills/softr-sdk/workflows/SKILL.md

@@ -9,7 +9,7 @@ description: >-
 metadata:
   type: sub-skill
   library: softr-sdk
-  library_version: 0.0.41
+  library_version: 0.0.43
 ---
 
 **Boundary.** `workflow` lives on `@softr/sdk/server` and runs only inside a `createServerFn` handler — importing it into a component fails the build. `defineWorkflow` and every type come from `@softr/sdk` and can be imported anywhere. Load the core `softr-sdk` skill only if you are unsure this is the right sub-skill.
@@ -28,7 +28,7 @@ import { workflow } from '@softr/sdk/server'
 
 ## Declare the workflow action
 
-Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent.
+Every trigger needs a workflow action: which workflow, which trigger step, who may run it, and any data that is always sent. The workflow must have a **Run custom workflow** trigger — no other trigger type can be fired from app code.
 
 ```ts
 const sendWelcomeEmail = defineWorkflow({
@@ -45,7 +45,7 @@ const sendWelcomeEmail = defineWorkflow({
 ```
 
 - `id` is a name you choose, unique across the app.
-- `workflowId` and `triggerId` are opaque UUIDs from the workflow definition in the Softr UI. Pass them as inline string literals — never derive them at runtime.
+- `workflowId` and `triggerId` are opaque UUIDs identifying the workflow and its **Run custom workflow** trigger. `list_workflows` returns both. Pass them as inline string literals — never derive them at runtime.
 - `permissions` declares who may run the trigger. Uses the same format as queries and mutations.
 - `body` is hardcoded data the server resolves before calling the workflow. It is **not** passed by the caller at runtime — the workflow always receives it. Template values draw from the signed-in user and the current time (see table below).
 
@@ -107,6 +107,8 @@ const submit = useServerFn(run)
 
 **Computing `workflowId` or `triggerId` at runtime.** Both are static UUIDs from the workflow definition. Derive them from user input and the call fails at request time.
 
+**Pointing at a workflow with no Run custom workflow trigger.** A workflow that runs on a schedule, a table event or an integration event has no trigger the app can call, and `workflow.trigger` fails at request time. Confirm the workflow has one before writing the `defineWorkflow`. If it does not, say which trigger it has instead — never that the workflow is missing — and name the ones that do have a Run custom workflow trigger.
+
 **Passing nested objects in the runtime payload.** The second argument to `workflow.trigger` only accepts flat values — `string`, `number`, `boolean`, or `null`. Put anything that needs server-side resolution in the action's `body` instead.
 
 **Not awaiting the result.** `workflow.trigger` is async. Fire-and-forget loses the result and swallows any error.